@amsterdamdatalabs/enact-extensions 0.1.37 → 0.1.47

package/extensions/enact-repo/skills/prototype/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: prototype
+description: Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
+disable-model-invocation: false
+---
+
+# Prototype
+
+A prototype is **throwaway code that answers a question**. The question decides the shape.
+
+## Use When
+
+- The user wants to sanity-check whether a state model or logic feels right before committing to it.
+- The user wants to explore what a UI should look like before building it for real.
+
+## Do Not Use When
+
+- The design question is already settled and the work is now production implementation — use `implement`.
+- The change's shape is already clear enough that no throwaway exploration is needed.
+
+## Pick a branch
+
+Identify which question is being answered — from the user's prompt, the surrounding code, or by asking if the user is around:
+
+- **"Does this logic / state model feel right?"** → [references/LOGIC.md](references/LOGIC.md). Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
+- **"What should this look like?"** → [references/UI.md](references/UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
+
+The two branches produce very different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
+
+## Rules that apply to both
+
+1. **Throwaway from day one, and marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
+2. **One command to run.** Whatever the project's existing task runner supports — `pnpm <name>`, `python <path>`, `bun <path>`, etc. The user must be able to start it without thinking.
+3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name.
+4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast.
+5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
+6. **Capture it when done.** Fold any validated decision into the real code, then capture the prototype itself as a **primary source**: commit it to a throwaway branch, out of main, and leave a context pointer to that branch on the implementation issue. Capture the answer too — the verdict and the question it settled — in the issue or a commit. The main branch keeps only the validated decision.

package/extensions/enact-repo/skills/prototype/references/LOGIC.md

@@ -0,0 +1,79 @@
+# Logic Prototype
+
+A tiny interactive terminal app that lets the user drive a state model by hand. Use this when the question is about **business logic, state transitions, or data shape** — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+## When this is the right shape
+
+- "I'm not sure if this state machine handles the edge case where X then Y."
+- "Does this data model actually let me represent the case where..."
+- "I want to feel out what the API should look like before writing it."
+- Anything where the user wants to **press buttons and watch state change**.
+
+If the question is "what should this look like" — wrong branch. Use [UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+
+Before writing code, write down what state model and what question you're prototyping. One paragraph, in the prototype's README or a comment at the top of the file. A logic prototype that answers the wrong question is pure waste — make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
+
+### 2. Pick the language
+
+Use whatever the host project uses. If the project has no obvious runtime (e.g. a docs repo), ask.
+
+Match the project's existing conventions for tooling — don't add a new package manager or runtime just for the prototype.
+
+### 3. Isolate the logic in a portable module
+
+Put the actual logic — the bit that's answering the question — behind a small, pure interface that could be lifted out and dropped into the real codebase later. The TUI around it is throwaway; the logic module shouldn't be.
+
+The right shape depends on the question:
+
+- **A pure reducer** — `(state, action) => state`. Good when actions are discrete events and state is a single value.
+- **A state machine** — explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
+- **A small set of pure functions** over a plain data type. Good when there's no implicit current state — just transformations.
+- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
+
+Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a TUI. Keep it pure: no I/O, no terminal code, no `console.log` for control flow. The TUI imports it and calls into it; nothing flows the other direction.
+
+This is what makes the prototype useful past its own lifetime: when the question's been answered, the validated reducer / machine / function set can be lifted into the real module on its own.
+
+### 4. Build the smallest TUI that exposes the state
+
+Build it as a **lightweight TUI** — on every tick, clear the screen (`console.clear()` / `print("\033[2J\033[H")` / equivalent) and re-render the whole frame. The user should always see one stable view, not an ever-growing scrollback.
+
+Each frame has two parts, in this order:
+
+1. **Current state**, pretty-printed and diff-friendly (one field per line, or formatted JSON). Use **bold** for field names or section headers and **dim** for less important context (timestamps, IDs, derived values). Native ANSI escape codes are fine — `\x1b[1m` bold, `\x1b[2m` dim, `\x1b[0m` reset. No need to pull in a styling library unless one is already in the project.
+2. **Keyboard shortcuts**, listed at the bottom: `[a] add user  [d] delete user  [t] tick clock  [q] quit`. Bold the key, dim the description, or vice-versa — whatever reads cleanly.
+
+Behaviour:
+
+1. **Initialise state** — a single in-memory object/struct. Render the first frame on start.
+2. **Read one keystroke (or one line)** at a time, dispatch to a handler that mutates state.
+3. **Re-render** the full frame after every action — don't append, replace.
+4. **Loop until quit.**
+
+The whole frame should fit on one screen.
+
+### 5. Make it runnable in one command
+
+Add a script to the project's existing task runner (`package.json` scripts, `Makefile`, `justfile`, `pyproject.toml`). The user should run `pnpm run <prototype-name>` or equivalent — never need to remember a path.
+
+If the host project has no task runner, just put the command at the top of the prototype's README.
+
+### 6. Hand it over
+
+Give the user the run command. They'll drive it themselves; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" — those are the bugs in the _idea_, which is the whole point. If they want new actions added, add them. Prototypes evolve.
+
+### 7. Capture the answer and the prototype
+
+Once the prototype has answered its question, capture the answer, then capture the prototype the way the [SKILL](SKILL.md) describes. The logic-specific mapping: the validated reducer / machine / function set lifts into the real module (the decision, absorbed); the TUI shell rides along to the throwaway branch that keeps the prototype as a primary source.
+
+## Anti-patterns
+
+- **Don't add tests.** A prototype that needs tests is no longer a prototype.
+- **Don't wire it to the real database.** Use an in-memory store unless the question is specifically about persistence.
+- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
+- **Don't blur the logic and the TUI together.** If the reducer / state machine references `console.log`, prompts, or terminal escape codes, it's no longer portable. Keep the TUI as a thin shell over a pure module.
+- **Don't ship the TUI shell into production.** The shell is optimised for being driven by hand from a terminal. The logic module behind it is the bit worth keeping.

package/extensions/enact-repo/skills/prototype/references/UI.md

@@ -0,0 +1,112 @@
+# UI Prototype
+
+Generate **several radically different UI variations** on a single route, switchable from a floating bottom bar. The user flips between variants in the browser, picks one (or steals bits from each), then throws the rest away.
+
+If the question is about logic/state rather than what something looks like — wrong branch. Use [LOGIC.md](LOGIC.md).
+
+## When this is the right shape
+
+- "What should this page look like?"
+- "I want to see a few options for this dashboard before committing."
+- "Try a different layout for the settings screen."
+- Any time the user would otherwise spend a day picking between three vague mockups in their head.
+
+## Two sub-shapes — strongly prefer sub-shape A
+
+A UI prototype is much easier to judge when it's **butting up against the rest of the app** — real header, real sidebar, real data, real density. A throwaway route on its own is a vacuum: every variant looks fine in isolation. Default to sub-shape A whenever there's a plausible existing page to host the variants. Only reach for sub-shape B if the prototype genuinely has no nearby home.
+
+### Sub-shape A — adjustment to an existing page (preferred)
+
+The route already exists. Variants are rendered **on the same route**, gated by a `?variant=` URL search param. The existing data fetching, params, and auth all stay — only the rendering swaps. This is the default; pick it unless there's a specific reason not to.
+
+If the prototype is for something that doesn't yet have a page but *would naturally live inside one* (a new section of the dashboard, a new card on the settings screen, a new step in an existing flow) — that's still sub-shape A. Mount the variants inside the host page.
+
+### Sub-shape B — a new page (last resort)
+
+Only use this when the thing being prototyped genuinely has no existing page to live inside — e.g. an entirely new top-level surface, or a flow that can't be embedded anywhere sensible.
+
+Create a **throwaway route** following whatever routing convention the project already uses — don't invent a new top-level structure. Name it so it reads as a prototype (e.g. include the word `prototype` in the path or filename). Same `?variant=` pattern.
+
+Before committing to sub-shape B, sanity-check: is there really no existing page this could be embedded in? An empty route hides design problems that a populated one would expose.
+
+In both sub-shapes the floating bottom bar is identical.
+
+## Process
+
+### 1. State the question and pick N
+
+Default to **3 variants**. More than 5 stops being radically different and starts being noise — cap there.
+
+Write down the plan in one line, in the prototype's location or a top-of-file comment:
+
+> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
+
+This works whether the user is here to push back or not.
+
+### 2. Generate radically different variants
+
+Draft each variant. Hold each one to:
+
+- The page's purpose and the data it has access to.
+- The project's component library / styling system (TailwindCSS, shadcn, MUI, plain CSS, whatever).
+- A clear exported component name, e.g. `VariantA`, `VariantB`, `VariantC`.
+
+Variants must be **structurally different** — different layout, different information hierarchy, different primary affordance, not just different colours. Three slightly-tweaked card grids isn't a UI prototype, it's wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance.
+
+### 3. Wire them together
+
+Create a single switcher component on the route:
+
+```tsx
+// pseudo-code — adapt to the project's framework
+const variant = searchParams.get('variant') ?? 'A';
+return (
+  <>
+    {variant === 'A' && <VariantA {...data} />}
+    {variant === 'B' && <VariantB {...data} />}
+    {variant === 'C' && <VariantC {...data} />}
+    <PrototypeSwitcher variants={['A','B','C']} current={variant} />
+  </>
+);
+```
+
+For sub-shape A (existing page): keep all the existing data fetching above the switcher; only the rendered subtree changes per variant.
+
+For sub-shape B (new page): the throwaway route under `/prototype/<name>` mounts the same switcher.
+
+### 4. Build the floating switcher
+
+A small fixed-position bar at the bottom-centre of the screen with three pieces:
+
+- **Left arrow** — cycles to the previous variant (wraps around).
+- **Variant label** — shows the current variant key and, if the variant exports a name, that name too. e.g. `B — Sidebar layout`.
+- **Right arrow** — cycles forward (wraps around).
+
+Behaviour:
+
+- Clicking an arrow updates the URL search param (use the framework's router — `router.replace` on Next, `navigate` on React Router, etc) so the variant is shareable and reload-stable.
+- Keyboard: `←` and `→` arrow keys also cycle. Don't intercept arrow keys when an `<input>`, `<textarea>`, or `[contenteditable]` is focused.
+- Visually distinct from the page (e.g. high-contrast pill, subtle shadow) so it reads as not part of the design being evaluated.
+- Hidden in production builds — gate on `process.env.NODE_ENV !== 'production'` or an equivalent check, so a stray prototype merge can't ship the bar to users.
+
+Put the switcher in a single shared component so both sub-shapes can reuse it. Locate it wherever shared UI lives in the project.
+
+### 5. Hand it over
+
+Surface the URL (and the `?variant=` keys). The user will flip through whenever they get to it. The interesting feedback is usually **"I want the header from B with the sidebar from C"** — that's the actual design they want.
+
+### 6. Capture the answer and clean up
+
+Once a variant has won, capture the answer — which variant and why — then capture the prototype the way the [SKILL](SKILL.md) describes. Fold the winner into the real code and move the rest onto the throwaway branch, not into main:
+
+- **Sub-shape A** — fold the winner into the existing page; drop the losing variants and the switcher from main.
+- **Sub-shape B** — promote the winning variant to a real route; drop the throwaway route and the switcher from main.
+
+The full set of variants is the primary source, so it lands on the throwaway branch, not the bin — variant components and the switcher left in the main branch rot fast and confuse the next reader.
+
+## Anti-patterns
+
+- **Variants that differ only in colour or copy.** That's a tweak, not a prototype. Real variants disagree about structure.
+- **Sharing too much code between variants.** A shared `<Header>` is fine; a shared `<Layout>` defeats the point. Each variant should be free to throw out the layout.
+- **Wiring variants to real mutations.** Read-only prototypes are fine. If a variant needs to mutate, point it at a stub — the question is "what should this look like", not "does the backend work".
+- **Promoting the prototype directly to production.** The variant code was written under prototype constraints (no tests, minimal error handling). Rewrite it properly when you fold it in.

package/extensions/enact-repo/skills/refactor-safely/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: refactor-safely
+description: "Use when the user wants to plan or execute a refactor — a rename, dead-code removal, decomposition, or restructuring — with dependency-aware confidence before touching code. USE FOR: renaming a function or symbol, checking the impact radius of a change before applying it, previewing every call site an edit touches, decomposing a large function, removing dead code, seeing what breaks before refactoring. DO NOT USE FOR: orienting in an unfamiliar codebase with no refactor in mind (use explore-codebase), chasing the cause of a live bug (use debug-issue), or reviewing someone else's pending diff (use review-changes)."
+disable-model-invocation: false
+---
+
+# Refactor Safely
+
+Use the knowledge graph to plan and execute refactoring with confidence.
+
+## Use When
+
+Planning or executing a refactor — a rename, dead-code removal, or
+decomposition — where you need dependency-aware confidence before touching
+code: an impact radius, the affected execution flows, or a preview of every
+edit location before applying a change.
+
+## Do Not Use When
+
+You are only orienting in an unfamiliar codebase with no refactor in mind —
+use `explore-codebase`. You are chasing the cause of a live bug — use
+`debug-issue`. You are reviewing someone else's pending diff — use
+`review-changes`.
+
+## Steps
+
+1. Use `refactor_tool` with mode="suggest" for community-driven refactoring suggestions.
+2. Use `refactor_tool` with mode="dead_code" to find unreferenced code.
+3. For renames, use `refactor_tool` with mode="rename" to preview all affected locations.
+4. Use `apply_refactor_tool` with the refactor_id to apply renames.
+5. After changes, run `detect_changes_tool` to verify the refactoring impact.
+
+## Safety Checks
+
+- Always preview before applying (rename mode gives you an edit list).
+- Check `get_impact_radius_tool` before major refactors.
+- Use `get_affected_flows_tool` to ensure no critical paths are broken.
+- Run `find_large_functions_tool` to identify decomposition targets.
+
+## Token Efficiency
+
+Follow `explore-codebase`'s **Token Efficiency Rules** — minimal-context
+first, `detail_level="minimal"`, a ≤5-call/≤800-token target, and read the
+real source before editing.

package/extensions/enact-repo/skills/remove-deadcode/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: remove-deadcode
+description: Remove explicitly enumerated code symbols only after entry-point and LSP reference checks prove deletion is safe.
+disable-model-invocation: false
+---
+
+# Remove Deadcode
+
+## Purpose
+
+Delete provably unused symbols without damaging runtime, generated, or dynamic entry points.
+
+## Use When
+
+- Candidates are already enumerated and the project has an LSP reference surface.
+- Cleanup needs a repeatable deletion gate rather than a broad refactor.
+
+## Do Not Use When
+
+- A symbol is still referenced, generated, dynamically reached, or needs restructuring.
+- The work is source cleanup inside live code rather than deletion of unreferenced symbols.
+
+## Workflow
+
+1. Enumerate candidates and load `remove-deadcode/entry-points.txt` when it exists.
+2. For each candidate, reject it if guarded; otherwise run `lsp_find_references`.
+3. Delete only candidates with exactly zero reliable references; recheck each parallel worker independently.
+4. Run the project's build or typecheck after every deletion batch.
+
+## Output
+
+The candidate list, guard decision, reference result, changed symbols, and build/typecheck evidence.
+
+## State Contract
+
+LSP zero references is necessary, not proof against reflection or string dispatch. Never use heuristic-only deletion, bypass a guard, or treat a partial index as zero.
+
+## Boundaries
+
+### In scope
+
+Safely delete an enumerated, unguarded symbol after a reliable zero-reference result.
+
+### Out of scope
+
+Execution-path analysis, refactoring live code, and authoring-residue cleanup are all outside this skill.
+
+### Fog of war
+
+If the index is stale, dynamic reachability is plausible, or no guard policy exists, leave the symbol and report the uncertainty.
+
+## Completion
+
+Paste `npm run build` or `tsc --noEmit` output after the final candidate batch; an LSP-only result is incomplete.

package/extensions/enact-repo/skills/research/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: research
+description: Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent.
+disable-model-invocation: false
+---
+
+# Research
+
+## Use When
+
+- The user wants a topic researched, docs or API facts gathered against primary sources.
+- Reading legwork should be delegated to a background agent instead of blocking the current conversation.
+
+## Do Not Use When
+
+- The answer is already known or trivially checkable without reading primary sources — just answer directly.
+- The task is implementation work rather than investigation — use `implement`.
+
+## Process
+
+Spin up a **background agent** to do the research, so you keep working while it reads.
+
+Its job:
+
+1. Investigate the question against **primary sources** — official docs, source code, specs, first-party APIs — not a secondary write-up of them. Follow every claim back to the source that owns it.
+2. Write the findings to a single Markdown file, citing each claim's source.
+3. Save it where the repo already keeps such notes; match the existing convention, and if there is none, put it somewhere sensible and say where.

package/extensions/enact-repo/skills/resolving-merge-conflicts/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: resolving-merge-conflicts
+description: "Use when you need to resolve an in-progress git merge/rebase conflict."
+disable-model-invocation: false
+---
+
+# Resolving Merge Conflicts
+
+## Use When
+
+- A `git merge` or `git rebase` is in progress and has left conflict markers to resolve.
+
+## Do Not Use When
+
+- No merge or rebase is currently in progress — there is nothing to resolve.
+- The goal is to abandon the merge/rebase (`--abort`); this skill always resolves and finishes, never aborts.
+
+## Steps
+
+1. **See the current state** of the merge/rebase. Check git history, and the conflicting files.
+
+2. **Find the primary sources** for each conflict. Understand deeply why each change was made, and what the original intent was. Read the commit messages, check the PRs, check original issues/tickets.
+
+3. **Resolve each hunk.** Preserve both intents where possible. Where incompatible, pick the one matching the merge's stated goal and note the trade-off. Do **not** invent new behaviour. Always resolve; never `--abort`.
+
+4. Discover the project's **automated checks** and run them — typically typecheck, then tests, then format. Fix anything the merge broke.
+
+5. **Finish the merge/rebase.** Stage everything and commit. If rebasing, continue the rebase process until all commits are rebased.

package/extensions/enact-repo/skills/review-changes/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: review-changes
+description: Perform a structured code review using change detection and impact
+disable-model-invocation: false
+---
+
+# Review Changes
+
+Perform a thorough, risk-aware code review using the knowledge graph.
+
+## Use When
+
+Reviewing a diff or pending change set and you need a structured, risk-aware
+pass — a risk score, the affected execution paths, test coverage status, and
+the blast radius — before recommending merge.
+
+## Do Not Use When
+
+You are planning your own refactor rather than reviewing one — use
+`refactor-safely`. You are chasing the cause of a live bug — use
+`debug-issue`. You just need to get oriented in an unfamiliar codebase — use
+`explore-codebase`.
+
+## Steps
+
+1. Run `detect_changes_tool` to get risk-scored change analysis.
+2. Run `get_affected_flows_tool` to find impacted execution paths.
+3. For each high-risk function, run `query_graph_tool` with pattern="tests_for" to check test coverage.
+4. Run `get_impact_radius_tool` to understand the blast radius.
+5. For any untested changes, suggest specific test cases.
+
+## Output Format
+
+Provide findings grouped by risk level (high/medium/low) with:
+- What changed and why it matters
+- Test coverage status
+- Suggested improvements
+- Overall merge recommendation
+
+## Token Efficiency
+
+Keep this review token-light per `explore-codebase`'s **Token Efficiency
+Rules**: `get_minimal_context_tool` first, `detail_level="minimal"` on every
+call, ≤5 calls and ≤800 tokens, and confirm findings against the actual source
+and tests.

package/extensions/enact-repo/skills/tailwind-4-docs/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: tailwind-4-docs
+description: Comprehensive Tailwind CSS v4 documentation snapshot and workflow guidance. Use when answering Tailwind v4 questions, selecting utilities/variants, configuring Tailwind v4, or migrating projects from v3 to v4 with official docs and gotcha checks.
+compatibility: Requires git, Python 3, and internet access to initialize the Tailwind docs snapshot from tailwindcss.com.
+disable-model-invocation: false
+---
+
+# Tailwind 4 Docs
+
+## Overview
+
+Use this skill to navigate a locally synced Tailwind CSS v4 documentation snapshot and answer development, configuration, and migration questions with official guidance.
+
+The docs snapshot is not bundled with this skill because the upstream repository is source-available but not open-source. Users must initialize the snapshot themselves and are responsible for complying with the upstream license.
+
+## Use When
+
+- Answering Tailwind CSS v4 questions about utilities, variants, or configuration.
+- Planning or executing a v3-to-v4 migration and needing official breaking-change guidance.
+- Verifying v4 browser compatibility or tooling requirements (`@tailwindcss/postcss`, `@tailwindcss/vite`, `@tailwindcss/cli`).
+
+## Do Not Use When
+
+- The question is about Tailwind CSS v3 syntax with no migration angle — this snapshot is v4-only and will surface wrong class names or removed utilities for a v3 project.
+- The docs need to be redistributed or published outside this workspace — `tailwindlabs/tailwindcss.com` is source-available, not open-source, and redistribution needs separate license review.
+- Git, Python 3, or network access are unavailable and no snapshot has ever been initialized — tell the user to consult the official docs directly instead of guessing.
+
+## Quick start
+
+1. Check whether the docs snapshot is initialized (`references/docs/` and `references/docs-index.tsx` exist).
+2. If the snapshot is missing or older than one week, stop and ask to run the initialization step in "Initialization" before continuing. Do not answer the user's question until the snapshot is initialized.
+3. Identify the topic (utility, variant, config, migration, compatibility).
+4. Find the matching doc via `references/docs-catalog.md` (or `references/docs-index.tsx`).
+5. Load only the relevant file from `references/docs/`.
+6. Apply guidance and call out any breaking changes or constraints.
+
+## Initialization (required once per install)
+
+Run the sync script to download the Tailwind docs locally. This requires network access, git, and Python 3:
+
+```
+python skills/tailwind-4-docs/scripts/sync_tailwind_docs.py --accept-docs-license
+```
+
+This pulls content from `tailwindlabs/tailwindcss.com`. That repo is source-available and explicitly not open-source, so the user must accept its license before downloading and keep the snapshot local.
+
+If you cannot run tools or have no internet access, ask the user to run the exact command above in a terminal, then continue once `references/docs/` and `references/docs-index.tsx` exist.
+
+If the snapshot is missing or older than one week, you must ask for permission to run the command or ask the user to run it. Do not proceed with Tailwind guidance until the snapshot is initialized or refreshed.
+
+If initialization is blocked (no internet or no write access), use `references/gotchas.md` as a limited fallback and ask the user to consult the official docs.
+
+## References map
+
+- `references/docs/` is generated locally and contains the Tailwind v4 MDX docs snapshot.
+- `references/docs-catalog.md` is generated locally and lists every synced doc page under `references/docs/`, grouped by category, as a plain-text table of contents.
+- `references/docs-index.tsx` is generated locally and contains the category and slug map used by the docs sidebar.
+- `references/docs-source.txt` captures the upstream repo, commit, and snapshot date (or reports that initialization is pending).
+- `references/gotchas.md` provides a quick scan of common v4 migration pitfalls.
+
+## MDX handling
+
+- Treat `export const title` and `export const description` as metadata.
+- Read JSX callouts like `<TipInfo>` or `<TipBad>` as guidance text.
+
+## Common entry points
+
+- Migration: `references/docs/upgrade-guide.mdx`, `references/docs/compatibility.mdx`.
+- Gotchas overview: `references/gotchas.md`.
+- Configuration and directives: `references/docs/functions-and-directives.mdx`, `references/docs/adding-custom-styles.mdx`, `references/docs/theme.mdx`.
+- Variants and responsive patterns: `references/docs/hover-focus-and-other-states.mdx`, `references/docs/responsive-design.mdx`.
+- Core behavior: `references/docs/preflight.mdx`, `references/docs/detecting-classes-in-source-files.mdx`.
+
+## Migration checklist
+
+When upgrading from v3 to v4, always confirm the following in the docs:
+
+- Browser support and compatibility expectations.
+- Tooling changes: `@tailwindcss/postcss`, `@tailwindcss/cli`, `@tailwindcss/vite`.
+- Import syntax: `@import "tailwindcss"` replaces `@tailwind` directives.
+- Utility renames/removals, prefix format, and important modifier placement.
+- Changes to variants, transforms, and arbitrary value syntax.
+
+## Update workflow
+
+Run `scripts/sync_tailwind_docs.py` to refresh the snapshot. Use `--local-repo` if you already have a local clone of `tailwindlabs/tailwindcss.com` to speed up syncs. Always pass `--accept-docs-license`.
+
+---