# BOOT.md — Fresh Expert LLM Startup Instructions

When the user says **"boot"** in a fresh session, read this file first, follow these instructions, then report what you are prepared with and ask what to do next.

## 1. Repository identity

This repository is a documentation-first Alpine.js + htmx training and architecture package. It is not primarily an application codebase yet. It teaches how to build rich, progressively enhanced, server-rendered web interfaces with Alpine.js and htmx as co-equal tools.

The core doctrine is:

1. **One authoritative owner per state value.**
   - Server/database own durable, shared, permission-sensitive truth.
   - URLs/routes own bookmarkable navigation state.
   - Native controls own submitted values whenever possible.
   - htmx owns request state and server-rendered HTML installation.
   - Alpine owns immediate, disposable browser-local interaction state.
   - Plain JavaScript islands own complex browser APIs or rich widgets when justified.
2. **One intentional writer per DOM boundary.**
   - htmx replaces server-owned regions.
   - Alpine controls stable local reactive regions.
   - Avoid allowing both tools to silently mutate the same DOM descendants.

The verified documentation baseline is **Alpine.js 3.15.12** and **htmx 2.0.10 / stable 2.x**, verified on **2026-07-19**. Treat htmx 4 guidance as version-gated prerelease/migration material, not a drop-in replacement for the htmx 2 examples.

## 2. First actions after booting

1. Confirm you are in the repository root.
2. Read these high-level files before making plans:
   - `README.md`
   - `MASTER_REPOSITORY_INDEX.md`
   - `EXAMPLE_WEBPAGE_SHOWCASE_IDEAS.md`
   - `alpine_htmx_onboarding/README.md`
   - `alpine_htmx_onboarding/manifest.json`
   - `alpine_htmx_onboarding/SOURCE_RECONCILIATION.md`
3. For curriculum details, read the 12 daily lessons in order:
   - `alpine_htmx_onboarding/01-start-here-ownership-and-boundaries.md`
   - `alpine_htmx_onboarding/02-alpine-local-ui-fundamentals.md`
   - `alpine_htmx_onboarding/03-htmx-request-target-swap-fundamentals.md`
   - `alpine_htmx_onboarding/04-forms-controls-and-server-validation.md`
   - `alpine_htmx_onboarding/05-request-state-concurrency-and-active-search.md`
   - `alpine_htmx_onboarding/06-component-lifecycle-and-dom-boundaries.md`
   - `alpine_htmx_onboarding/07-semantic-events-and-cross-boundary-contracts.md`
   - `alpine_htmx_onboarding/08-history-navigation-and-progressive-enhancement.md`
   - `alpine_htmx_onboarding/09-accessible-modals-drawers-and-inline-editing.md`
   - `alpine_htmx_onboarding/10-oob-updates-toasts-jobs-and-live-panels.md`
   - `alpine_htmx_onboarding/11-production-security-errors-testing-and-operations.md`
   - `alpine_htmx_onboarding/12-power-user-combination-showcase.md`
4. Use `alpine_htmx_onboarding/COMPLETE_ONBOARDING_PACKAGE.md` as the single-file full curriculum reference if full-text search or offline review is useful.
5. Read the companion guides when designing examples or architecture:
   - `alpine-htmx-companion-docs/alpine-for-htmx-developers.md`
   - `alpine-htmx-companion-docs/htmx-for-alpine-developers.md`
   - `alpine-htmx-companion-docs/alpine-and-htmx-as-coequals.md`
   - `alpine-htmx-companion-docs/alpine-htmx-superpowers.md`

After those reads, report that you are prepared with the repository map, doctrine, version baseline, curriculum structure, companion guide perspectives, showcase idea bank, and production/security/lifecycle constraints. Then ask the user what they want built or changed.

## 3. Mental model to preserve while building

Use this default responsibility table:

| Concern | Default owner |
| --- | --- |
| Durable truth, permissions, validation, transactions, audit, conflict handling | Server/database |
| Canonical representation of server state | Server templates |
| Meaningful navigation, direct visits, refresh-safe state, sharing | URLs/routes |
| Structure, semantics, labels, forms, links, successful controls | HTML |
| Layout, visual presentation, responsive behavior, ordinary transitions | CSS |
| HTTP requests, triggers, targets, swaps, request coordination, history, OOB swaps | htmx |
| Open/closed, selected, focused, expanded, provisional, dismissed, local preferences | Alpine |
| Browser APIs, charts, editors, maps, scanners, high-frequency rendering | Isolated JavaScript island |
| Communication between ownership boundaries | Semantic browser events |

Ask these questions for every component:

- What state values exist, and who owns each one?
- What DOM regions exist, and who writes each one?
- Which values are submitted through native controls?
- Which htmx target is replaced, and does the response root match the swap contract?
- Which Alpine state should reset, survive, be preserved, or be reconciled?
- What semantic events cross boundaries?
- What happens on validation failure, network failure, auth failure, and unexpected server failure?
- Where does focus go after swaps, validation, modal open/close, and errors?
- Does the direct URL or normal form/link path still work without JavaScript enhancement?

## 4. Preferred component patterns

Use these shapes before inventing a larger abstraction:

1. **Alpine-only local component**
   - For disclosures, dropdowns, local tabs, counters, previews, copy buttons, density toggles, local filters over already-present markup, and browser-only preferences.
2. **htmx-only server component**
   - For server-rendered fragments, pagination, row refresh, simple actions, and forms where no local state is required.
3. **Stable Alpine shell with htmx interior**
   - For modals, drawers, command palettes, detail panes, live dashboards, remote tabs, and panels whose local chrome should survive server content swaps.
4. **htmx-replaceable component with disposable Alpine behavior**
   - For inline editors, cards, rows, submitted forms, and widgets where local state should intentionally reset after replacement.
5. **Semantic event handshake**
   - For Alpine confirmation dialogs triggering htmx requests, server success closing local shells, toasts, OOB-adjacent reactions, and cross-boundary coordination.
6. **Isolated JavaScript island**
   - For date pickers, charts, maps, scanners, editors, or other rich widgets with explicit initialization and cleanup.

## 5. htmx guidance to follow

- Prefer real `href` and `action` baselines, then enhance with htmx.
- Use the HTTP method that matches intent: GET retrieves; POST creates/commands; PUT/PATCH update; DELETE deletes when the server and routing support it.
- Keep `hx-target` narrow. Do not broad-swap pages or Alpine roots accidentally.
- Match response markup to `hx-swap`; use `outerHTML` only when replacing the target itself is intended.
- Use `hx-indicator`, the `htmx-request` class, and `hx-disabled-elt` for factual request state instead of duplicating `loading` in Alpine.
- Use debounce/delay/throttle and `hx-sync` intentionally for active search, repeated commands, and race safety.
- Use `hx-push-url` for meaningful navigable results and `hx-replace-url` for ephemeral refinements.
- Use OOB swaps only for related authoritative server projections; avoid OOB sprawl.
- For long-running work, model jobs explicitly with server-owned status, polling/SSE/WebSockets, retry/cancel semantics, and accessible status announcements.
- In htmx 2, expected validation HTML should usually return a swap-eligible status such as 200 unless error swapping is deliberately configured and tested.

## 6. Alpine guidance to follow

- Keep `x-data` small and local. Extract `Alpine.data()` only when the component grows or repeats.
- Good Alpine state is cheap to lose on refresh.
- Do not put permissions, prices, inventory, durable entities, workflow truth, or server validation facts solely in Alpine.
- Use native controls as the bridge for values the server needs; avoid hidden duplicate Alpine-only form models.
- Use `x-show` for visibility toggles where DOM should remain; use `x-if` only when creation/destruction is intentional.
- Use `x-text` for untrusted text. Avoid `x-html` unless the HTML is trusted and sanitized.
- Use `$refs`, `$nextTick`, `$watch`, `init()`, and `destroy()` deliberately; clean up timers, observers, and third-party widgets.
- If Alpine creates markup containing `hx-*`, process only the newly inserted subtree with `htmx.process()` after Alpine has rendered it.

## 7. Events contract doctrine

Use semantic browser events to coordinate independent owners.

- Name events by domain meaning, not implementation detail.
- Use command/intent names for requests: `record-delete-requested`, `dialog-close-requested`, `orders:archive-requested`.
- Use past-tense fact names for completed outcomes: `record-saved`, `cart:item-added`, `profile:saved`, `job-completed`.
- Document producer, listener, payload, timing, bubbling scope, failure behavior, and version-sensitive mechanics.
- Prefer narrow scopes and local listeners over global event soup.
- Do not smuggle a full duplicated server model through event payloads; pass identifiers and facts needed for the interaction.

## 8. Accessibility, security, and production constraints

Accessibility is not optional:

- Use native controls and labels first.
- Preserve keyboard operation.
- Restore or move focus deliberately after swaps, validation errors, modal open/close, inline edits, and navigation.
- Use `aria-busy`, `role="status"`, live regions, and reduced-motion-friendly indicators where appropriate.
- Ensure direct URLs and normal forms/links work as a baseline whenever feasible.

Security authority remains server-side:

- Browser state is never authorization.
- Escape untrusted values in server templates.
- Sanitize deliberately allowed rich HTML with an allowlist.
- Avoid unsafe `x-html` and untrusted executable attributes.
- Use normal framework CSRF defenses with htmx-enhanced forms.
- Apply CSP-compatible Alpine patterns when production constraints require them.
- Treat auth/session failures, network failures, expected validation, business rejection, and unexpected server errors as different cases.

Testing strategy should include:

- Server route/template tests for full pages and fragments.
- Component-level checks for Alpine local behavior when available.
- Browser integration tests for swaps, OOB updates, lifecycle, race safety, focus, history, and accessibility.
- Contract tests for semantic events when coordination is important.

## 9. Showcase webpage mission context

The user plans to paste this boot file into a fresh expert LLM session and ask it to build a webpage that showcases basics and advanced capabilities of this Alpine + htmx application. Be ready to design a tutorial/showcase page or site using the repository's `EXAMPLE_WEBPAGE_SHOWCASE_IDEAS.md` as an idea bank.

A strong showcase should include a progressive path from fundamentals to advanced composition, such as:

- ownership classifier or DOM ownership heatmap;
- Alpine-only local UI demos;
- htmx request/target/swap demos;
- native form + server validation patterns;
- active search with race-safety explanation;
- stable Alpine modal/drawer shell with htmx-loaded body;
- inline editing with disposable Alpine state;
- semantic event handshake demo;
- OOB updates plus toast center;
- polling/SSE-style job status panel;
- history-aware search or remote tabs;
- production/security/accessibility checklist panel;
- capstone dashboard combining command palette, live panels, toasts, jobs, forms, and narrow swaps.

While building the page, explicitly label ownership boundaries and explain why each pattern is safe.

## 10. Boot report template

After reading this file and the repository documents, respond with a concise report like:

> Boot complete. I am prepared with:
> - the repository map and documentation structure;
> - the Alpine + htmx co-equal doctrine;
> - the Alpine 3.15.12 / htmx 2.0.10 baseline and htmx 4 warning;
> - the 12-day curriculum topics;
> - companion-guide perspectives for Alpine-first, htmx-first, architecture, and advanced composition;
> - showcase webpage ideas from fundamentals through capstone dashboards;
> - production constraints for accessibility, security, errors, lifecycle, events, testing, and progressive enhancement.
>
> What should I build or change next?