# Master Repository Index

## Repository identity

This repository is a documentation-first training package for building applications with Alpine.js and htmx as complementary, web-native tools. Its central doctrine is that server-rendered HTML, native browser behavior, and small local interaction islands can produce rich applications without turning every feature into a client-side application.

## Index compilation note

This index was compiled after reading every tracked repository document twice. The first pass established file coverage, structure, and major themes. The second pass reconciled repeated doctrine across the onboarding curriculum, complete package, source audit, manifest, and companion guides.

## Repository map

| Path | Role | Notes |
| --- | --- | --- |
| `alpine_htmx_onboarding/` | Primary 12-day curriculum | Daily lessons, package README, manifest, full combined package, and source reconciliation audit. |
| `alpine-htmx-companion-docs/` | Companion reference essays | Role-reversal guides, co-equal architecture doctrine, and advanced combined-superpower patterns. |
| `MASTER_REPOSITORY_INDEX.md` | Repository-level index | This generated master guide to files, concepts, and reading paths. |
| `README.md` | Root project README | A polished entry point for the whole repository. |
| `EXAMPLE_WEBPAGE_SHOWCASE_IDEAS.md` | Tutorial-site idea bank | One hundred potential example webpages for a combined Alpine.js + htmx tutorial and showcase site. |

## Core doctrine

### Two constitutional rules

1. **One authoritative owner per state value.** Server/domain facts belong to the server; local presentation state belongs to Alpine; real form values should live in native controls whenever possible.
2. **One intentional writer per DOM boundary.** htmx should replace server-owned regions; Alpine should control local reactive behavior inside its own stable boundaries; neither should silently compete over the same subtree.

### Preferred component shapes

- **Stable Alpine shell with htmx interior:** Alpine owns local chrome such as open/closed, focus, transient labels, and client-only affordances; htmx owns the replaceable server representation inside.
- **htmx-replaceable component with disposable Alpine behavior:** Alpine state is intentionally reset whenever htmx replaces the component.
- **htmx-only server component:** The server returns HTML and htmx swaps it into the correct target; no local state machinery is needed.
- **Alpine-only local component:** Local toggles, menus, tabs, counters, preview state, and non-authoritative UI belong here.
- **Event-mediated handshake:** Semantic browser events bridge local commands and server facts without creating hidden shared ownership.
- **Isolated JavaScript island:** Rich third-party or specialty behavior is allowed when it has a clear boundary, initialization, and cleanup plan.

## Primary curriculum: `alpine_htmx_onboarding/`

### Package metadata

- `manifest.json` records the package title, verification date, stable baseline, lesson count, lesson word counts, line counts, and SHA-256 hashes.
- The verified baseline is Alpine.js 3.15.12 and htmx 2.0.10, with explicit version discipline around htmx 4 because it is not treated as a drop-in compatible target.
- The curriculum contains 12 daily lessons plus a combined package, README, and source reconciliation document.

### Daily lessons

| Day | File | Focus | Key outputs |
| --- | --- | --- | --- |
| 1 | `01-start-here-ownership-and-boundaries.md` | Ownership, boundaries, and the web-native mental model | Classify state owners, avoid two DOM writers, establish first component contracts. |
| 2 | `02-alpine-local-ui-fundamentals.md` | Alpine local UI | Use `x-data`, `x-on`, `x-show`, `x-if`, `x-bind`, `x-text`, `x-model`, methods, refs, stores, and accessibility patterns appropriately. |
| 3 | `03-htmx-request-target-swap-fundamentals.md` | htmx request/trigger/target/swap fundamentals | Choose HTTP methods, shrink targets, design responses, and preserve progressive-enhancement baselines. |
| 4 | `04-forms-controls-and-server-validation.md` | Forms and validation | Keep values in native controls, use server validation, handle local previews, file uploads, focus, and announcements. |
| 5 | `05-request-state-concurrency-and-active-search.md` | Request state and race safety | Use htmx indicators, disabled elements, debounce, stale-result protection, and `hx-sync` intentionally. |
| 6 | `06-component-lifecycle-and-dom-boundaries.md` | Lifecycle and DOM boundaries | Decide between reset, survive, preserve, and reconcile; initialize and clean up Alpine and third-party widgets. |
| 7 | `07-semantic-events-and-cross-boundary-contracts.md` | Semantic events | Name command and fact events, pass payloads, time events, avoid event soup, and test contracts. |
| 8 | `08-history-navigation-and-progressive-enhancement.md` | History and navigation | Use URL ownership, GET routes, `hx-push-url`, `hx-replace-url`, direct visits, cache variation, remote tabs, pagination, and `hx-boost`. |
| 9 | `09-accessible-modals-drawers-and-inline-editing.md` | Modals, drawers, remote forms, inline editing | Keep stable overlay shells, avoid premature closes, manage focus, handle conflicts, and reset intentionally. |
| 10 | `10-oob-updates-toasts-jobs-and-live-panels.md` | OOB swaps, toasts, jobs, live panels | Separate authoritative multi-region updates from transient local presentation; use polling, SSE, and WebSockets carefully. |
| 11 | `11-production-security-errors-testing-and-operations.md` | Production readiness | Apply security authority, XSS/CSRF/CSP doctrine, error taxonomy, testing layers, naming, code review, and troubleshooting. |
| 12 | `12-power-user-combination-showcase.md` | Advanced composition | Build command palettes, transaction cockpits, incident centers, workflow consoles, and capstone operations dashboards. |

### Supporting onboarding files

#### `alpine_htmx_onboarding/README.md`

The package README explains the curriculum purpose, recommended sequence, daily rhythm, required proof of learning, version discipline, facilitator grading rubric, and package file list.

#### `alpine_htmx_onboarding/COMPLETE_ONBOARDING_PACKAGE.md`

The complete package concatenates all 12 daily lessons into one long-form document. It is best for offline reading, single-file distribution, or full-text searching across the curriculum.

#### `alpine_htmx_onboarding/SOURCE_RECONCILIATION.md`

The source reconciliation document audits and qualifies technical claims. It records the source inventory, reconciliation method, official version verification, corrections, cross-document consistency, claims not promoted to universal rules, and final audit outcome.

#### `alpine_htmx_onboarding/manifest.json`

The manifest is the machine-readable inventory for the onboarding package. It provides titles, line counts, word counts, hashes, package files, companion files, source documents, and verification metadata.

## Companion documents: `alpine-htmx-companion-docs/`

| File | Audience | Purpose |
| --- | --- | --- |
| `alpine-for-htmx-developers.md` | Developers who already know htmx | Teaches Alpine’s local-reactivity model using htmx-friendly comparisons and pitfalls. |
| `htmx-for-alpine-developers.md` | Developers who already know Alpine | Teaches htmx’s server-HTML request model using Alpine-friendly comparisons and pitfalls. |
| `alpine-and-htmx-as-coequals.md` | Architects and team leads | Defines the co-equal operating model, component shapes, communication doctrine, lifecycle doctrine, security, naming, contracts, and anti-patterns. |
| `alpine-htmx-superpowers.md` | Advanced practitioners | Shows high-leverage combined architectures: stable shells, live interiors, event diplomacy, multi-region updates, jobs, optimistic flows, and advanced lifecycle choices. |

## Concept index

### Accessibility

Covered throughout local components, forms, lifecycle, navigation, overlays, and production review. Key recurring requirements include native controls, labels, focus restoration, announcements, dialog semantics, keyboard behavior, and progressive enhancement.

### Alpine.js

Alpine is presented as the owner of local, disposable, browser-only interaction state. The curriculum emphasizes `x-data`, event handling, visibility, binding, text rendering, form bridges, lifecycle hooks, stores as exceptions, refs, effects, watchers, cleanup, and isolated widget boundaries.

### htmx

htmx is presented as the owner of server-HTML interaction: HTTP methods, triggers, targets, swaps, request indicators, concurrency controls, history, boosted navigation, out-of-band swaps, server response headers, polling, SSE, WebSockets, and progressive-enhancement baselines.

### Forms

Forms are the strongest shared bridge between Alpine and htmx because native controls can hold submitted values while Alpine supplies local presentation and htmx submits to authoritative server validation.

### Events

Semantic browser events are the preferred cross-boundary contract. Commands request work; facts announce outcomes. Event names, payloads, timing, bubbling scope, and tests should be explicit.

### Lifecycle

Every mixed component should declare whether replacement should reset, survive, preserve, or reconcile state. The docs repeatedly warn against accidental replacement of Alpine roots, repeated initialization, missing cleanup, blanket preservation, and unnecessary morphing.

### Request state and concurrency

Factual request state belongs to htmx. Use indicators, disabled controls, debounce, queue/drop/abort/replace sync strategies, idempotency, stale-result protection, and a separate model for long-running server jobs.

### Navigation and history

URL-addressable state belongs in routes and GET forms. Direct visits, cache variation, push/replace URL decisions, pagination, remote tabs, focus, scroll, and progressive enhancement are treated as first-class design requirements.

### Production readiness

The production lesson and reconciliation audit emphasize server-side authority, XSS boundaries, CSRF, CSP, expected and unexpected errors, narrow global listeners, server tests, Alpine tests, browser integration tests, naming, component contracts, and operational troubleshooting.

## Example webpage showcase bank

`EXAMPLE_WEBPAGE_SHOWCASE_IDEAS.md` provides a long, expanded list of potential example pages for a combined tutorial and showcase site. The ideas range from small foundational demos to production operations pages and capstone dashboards. Categories include foundations, forms and validation, search and navigation, lifecycle and DOM boundaries, semantic events, out-of-band updates, production operations, showcases, and tutorial-site meta pages.

## Recommended reading paths

### New team member path

1. Read `README.md`.
2. Read `alpine_htmx_onboarding/README.md`.
3. Complete Days 1 through 12 in order.
4. Use `COMPLETE_ONBOARDING_PACKAGE.md` for review.
5. Read the companion guide that matches your prior experience.
6. Finish with `alpine-and-htmx-as-coequals.md` and `alpine-htmx-superpowers.md`.

### htmx-first path

1. `alpine-htmx-companion-docs/alpine-for-htmx-developers.md`
2. Day 1, Day 2, Day 6, Day 7
3. Day 4 and Day 5 for forms and request state
4. Day 11 for production review

### Alpine-first path

1. `alpine-htmx-companion-docs/htmx-for-alpine-developers.md`
2. Day 1, Day 3, Day 4, Day 8
3. Day 6 and Day 7 for lifecycle and events
4. Day 11 for production review

### Architecture review path

1. `alpine-htmx-companion-docs/alpine-and-htmx-as-coequals.md`
2. `alpine_htmx_onboarding/11-production-security-errors-testing-and-operations.md`
3. `alpine_htmx_onboarding/SOURCE_RECONCILIATION.md`
4. `alpine-htmx-companion-docs/alpine-htmx-superpowers.md`

## Review checklists

### Component checklist

- What state values exist, and who owns each one?
- What DOM regions exist, and who writes each one?
- Which values are native form controls?
- Which htmx target is replaced?
- Which Alpine state resets, survives, or is preserved?
- What semantic events cross boundaries?
- What happens on validation failure, network failure, and authorization failure?
- Where does focus go after swaps or errors?
- How is cleanup performed?
- Does the direct URL still work without JavaScript enhancement?

### Anti-pattern checklist

- Alpine shadow backend.
- htmx request for local trivia.
- Duplicated loading state.
- Duplicated form models.
- Broad destructive swaps.
- Competing collection renderers.
- Event maze or event soup.
- Store sprawl.
- OOB sprawl.
- Blanket preservation or morphing.
- Attribute overload.

## Maintenance guidance

- Keep the manifest synchronized when lesson contents change.
- Re-run source reconciliation when Alpine or htmx versions change.
- Preserve the distinction between stable htmx 2 guidance and future htmx 4 evaluation.
- Prefer adding focused companion notes over weakening the constitutional ownership rules.
- Keep examples progressive-enhancement-friendly unless the document explicitly discusses an exceptional island.