bearings 0.2.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bearings",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Give your AI agents their bearings — scaffold an agent-friendly setup in any repository.",
   "type": "module",
   "engines": {

package/templates/AGENTS.md

@@ -1,43 +1,28 @@
 # <agent: project name> - Agent Seed
 
-Read this first. Load deeper context only when the task matches.
+## Setup Required
 
-## Project
-
-<agent: fill during handoff — Short summary of what this repo is, who uses it, and what it produces.>
-
-## Where To Read What
+Until this section is removed, do not inspect, modify, or run anything in this repository except `/setup-repo`. For every other request, respond only: Run `/setup-repo` to finalize bearings, then retry your request.
 
-| You need... | Read |
-|---|---|
-| What exists today and where things live | `docs/CURRENT_STATE.md` |
-| Durable architecture and decisions | `docs/ARCHITECTURE.md`, `docs/adr/` |
-| Deferred work | `docs/deferred/INDEX.md` |
-
-## Load On Demand
-
-| When you are... | Load skill |
-|---|---|
-| finding where code lives or which docs to read | `repo-navigation` |
-| touching secrets, credentials, keys, tokens, or config containing secrets | `secrets-handling` |
-| implementing a planned task | `implementing-task` |
-| adding dependencies | `installing-dependencies` |
-| fixing failed checks | `enforcement-gates` |
-| about to commit | `commit-convention` |
-| building something listed in deferred work | `resurface-deferred-work` |
+## Project
 
-## Hard Invariants
+<agent: fill during handoff — One sentence: problem, primary users, and outcome.>
 
-- <agent: fill during handoff — Invariant 1 with required skill/doc.>
-- <agent: fill during handoff — Invariant 2 with required verification.>
+Primary stack: <agent: fill during handoff — language/runtime/framework/platform>. Details: `docs/ARCHITECTURE.md`.
 
-## Always-On Rules
+## Knowledge Routing
 
-- Read `docs/CURRENT_STATE.md` before broad exploration.
-- Do not read archived or generated folders unless explicitly needed.
-- Do not silently rewrite durable docs during unrelated work.
-- Before claiming completion, run the smallest relevant verification command or say why it could not run.
+| Work | Read | How |
+|---|---|---|
+| User behavior, requirements, workflows, terminology, scope, or domain rules | `docs/DOMAIN.md` | Read before behavior or requirements work. |
+| Components, dependency direction, integrations, state ownership, significant dependencies, runtime/build shape, or local setup | `docs/ARCHITECTURE.md` | Read before structural or environment work. |
+| Locating, explaining, changing, or debugging source | `docs/CODEBASE_MAP.md` | Read the entire file before source work, then follow its `path#symbol` anchors. |
+| A consequential domain or technical decision | `docs/adr/INDEX.md` | Read the index first, then only matching ADRs. |
+| Planning a new capability | `docs/deferred/INDEX.md` | Read the index first, then only matching deferred details. |
 
-## Setup Status
+## Response Style
 
-Setup pending — run /setup-repo. <agent: remove this section when handoff is complete>
+- Lead with the answer; omit preamble and restatement.
+- Use the shortest clear structure: line, bullets, table, tree, or flow.
+- Preserve exact identifiers, paths, commands, errors, and code.
+- Report progress only for discoveries, decisions, or blockers; finish with changes and verification.

package/templates/agents/commands/refresh-repo-map.md

@@ -0,0 +1,161 @@
+---
+description: Reconcile the domain, architecture, current codebase map, and C4 component source when meaningful repository drift or staleness is detected
+---
+
+# /refresh-repo-map
+
+Reconcile the repository's knowledge maps with current evidence. This command is
+the exclusive writer for `docs/DOMAIN.md`, `docs/ARCHITECTURE.md`,
+`docs/CODEBASE_MAP.md`, and `docs/diagrams/c4-component.puml`. No other task may
+edit these four artifacts directly.
+
+Run it when committed changes alter business capabilities, workflows,
+terminology, domain rules, stable technical shape, dependencies, integrations,
+environment, capability ownership, module routes, utilities, interfaces,
+state, hazards, verification paths, or C4 component topology — or when an
+agent or developer detects staleness. Do not run it after every code edit
+when the maps remain accurate.
+
+## Ownership
+
+| Artifact | Owner |
+|---|---|
+| `docs/DOMAIN.md` | this command |
+| `docs/ARCHITECTURE.md` | this command |
+| `docs/CODEBASE_MAP.md` | this command |
+| `docs/diagrams/c4-component.puml` | this command |
+
+Always create `docs/diagrams/` and `c4-component.puml` when absent. Maintain
+source-only PlantUML: never render it and never modify another diagram.
+
+## Artifact Contracts
+
+| Artifact | Authority | Required output |
+|---|---|---|
+| `docs/DOMAIN.md` | User-confirmed business intent plus observable shipped behavior | problem and outcomes, actors, use cases, workflows, ubiquitous language, domain rules, boundaries/non-goals |
+| `docs/ARCHITECTURE.md` | Accepted ADRs plus running configuration and code | system boundary, primary stack, significant dependencies, components/dependency direction, integrations/state ownership, runtime/deployment, development environment, architectural constraints |
+| `docs/CODEBASE_MAP.md` | Running code, configuration, and tests | executable entry points, capabilities/concerns by `path#symbol`, critical flows, shared utilities/infrastructure, interfaces/state, change hazards, verification map |
+| `docs/diagrams/c4-component.puml` | Reconciled architecture plus implemented component relationships | source-only PlantUML component topology; never render it |
+
+`docs/CODEBASE_MAP.md` has no fixed size cap. Every retained line must route
+source work, establish current behavior needed to select code, prevent an
+unsafe change, or identify verification evidence.
+
+Each Markdown artifact ends with this exact marker:
+
+```markdown
+<!-- repo-map-synced: <commit-sha> -->
+```
+
+The PlantUML artifact ends with this exact marker:
+
+```text
+' repo-map-synced: <commit-sha>
+```
+
+Each marker records the pre-command `HEAD` whose relevant evidence was
+reconciled for that specific artifact. It is an incremental search baseline,
+not freshness proof by itself.
+
+## Evidence and Conflicts
+
+Treat evidence in this order per artifact, using each artifact's own
+authority row above: running code/configuration/tests, then accepted ADRs
+and durable domain rules, then confirmed user/developer intent, then
+existing map wording.
+
+- Business intent versus implementation: expose the conflict and ask one
+  focused question with a recommended resolution. Never silently redefine
+  the domain from code.
+- Implementation versus an accepted ADR or architectural constraint: ask
+  whether the implementation should change or the decision should be
+  superseded, and recommend a path from the available evidence.
+- An unresolved conflict blocks that artifact's refresh: leave the affected artifact unchanged and report the conflict rather than publishing a falsely coherent map. Unaffected artifacts may still refresh independently.
+
+## Baselines and Mode Selection
+
+Each artifact records its own reconciliation baseline, so mode selection is
+independent per artifact:
+
+- Full reconciliation when the artifact (or the C4 source) is missing, its
+  marker is missing, malformed, unavailable locally, or not an ancestor of
+  pre-command `HEAD`, the user requests a full refresh, or incremental
+  evidence reveals structural drift outside the expected impact closure.
+- Incremental reconciliation when the artifact exists and its marker names
+  an available ancestor of pre-command `HEAD`.
+
+## Full Reconciliation
+
+1. Capture pre-command `HEAD` as the reconciliation baseline.
+2. Read manifests, build configuration, and executable entry points.
+3. Identify module boundaries through exports, imports, registration sites,
+   and ownership directories.
+4. Trace public interfaces, external integrations, state stores, and
+   schemas when present.
+5. Trace implementations and tests for critical flows and hazards.
+6. Read accepted ADRs and confirmed domain/business intent that constrain
+   current code.
+7. Reconcile the artifact's complete required output and the C4 component
+   model when its topology is in scope.
+8. Set that artifact's sync marker to the captured pre-command `HEAD` only
+   after its reconciliation succeeds.
+
+File size is not an architecture signal. Never select a module by choosing
+its largest file.
+
+## Incremental Reconciliation
+
+1. Capture pre-command `HEAD`; parse the artifact's own marker and verify
+   its commit exists locally.
+2. Verify the marker is an ancestor of pre-command `HEAD`; otherwise switch
+   that artifact to full reconciliation.
+3. Inspect every changed source, config, test, and durable-doc path from
+   the marker's commit through pre-command `HEAD` that is relevant to that
+   artifact's authority.
+4. Expand each changed path to its direct callers/callees and co-change
+   relationships to establish impact closure.
+5. Edit only the affected sections of that artifact and preserve unrelated
+   verified content.
+6. Update the C4 model only when component boundaries or relationships
+   changed.
+7. Set that artifact's sync marker to the captured pre-command `HEAD` only
+   after its reconciliation succeeds.
+8. Escalate that artifact to full reconciliation when impact closure cannot
+   be established with confidence.
+
+## Validation and Routing Probes
+
+Before reporting completion:
+
+1. Validate every retained path, symbol, command, and relationship against
+   the repository.
+2. Run these probes in fresh context that receives only the draft
+   artifacts and the scenario, never the source-reading context:
+   - Explain: select a critical behavior; identify entry point, flow,
+     state/side effects, failure semantics, and targeted source.
+   - Feature: select a plausible extension; identify owner, extension seam,
+     affected contracts/state, co-change edges, and tests.
+   - Bug: select a plausible public symptom; narrow diagnosis to an owning
+     flow, likely files, and regression-test location.
+3. Rerun any failed probe after adding the missing knowledge. A failed
+   probe blocks completion for the affected artifact.
+
+## Completion
+
+1. Show the diff for every changed owned artifact.
+2. Show the evidence used per changed artifact and any unresolved
+   conflicts, naming the artifact each conflict blocked.
+3. Update only the sync marker of each artifact whose reconciliation
+   succeeded; leave unresolved artifacts and their markers unchanged.
+4. Leave all changes uncommitted for the normal review and commit workflow.
+
+## Boundaries
+
+- Keep this command generic: no project-specific scanning heuristics or
+  named project files beyond the four owned artifact paths.
+- Do not create or register skills, render the PlantUML diagram, add a
+  fixed map size cap, or modify unrelated documentation.
+- Do not create commits; leave staging and commit decisions to the
+  developer.
+- Do not treat a marker, task intent, or existing wording as stronger
+  evidence than running code, configuration, and tests.

package/templates/agents/commands/setup-repo.md

@@ -10,40 +10,74 @@ the developer relentlessly — one question at a time, with a recommended
 answer per question — and explore the code before asking anything the code
 can answer.
 
+This is the only operation the temporary `## Setup Required` gate in
+`AGENTS.md` permits. Do not remove the gate until step 10 below.
+
+## Post-update reconciliation
+
+When `.agents/bearings.json` is manifest v2 and has `setupPending`:
+
+1. Read every file record's ordered `reconciliations`.
+2. For each reconciliation, read its Backup File and current target, summarize
+   the differences, and ask which backed-up changes to apply to the target.
+3. Apply the developer's choice directly to the target regardless of owner,
+   delete the resolved Backup File, and remove its reconciliation record.
+4. A `skippedTemplate` records a declined template revision.
+   Do not apply the declined template — normal project maintenance may
+   still update that file.
+5. Run only setup steps supported by current drift; do not reset completed
+   project tailoring.
+6. Run `bearings verify`. Resolve every failure and warning except the
+   expected `setup-pending` warning, then remove `setupPending` from the
+   manifest.
+7. Run `bearings verify` again and finish only at zero failures and warnings.
+
 ## Required workflow
 
-1. Read `AGENTS.md`, `docs/conventions/doc-lifecycle.md`,
-   `docs/conventions/current-state.md`, and `.agents/bearings.json`.
-2. Review Backup Files: for every manifest entry with a `backup`, read the
-   backup, summarise what it contained, and ask the developer per file:
-   merge into the new scaffold / keep parts / discard. Apply their choice,
-   then delete the `.bkp` file once resolved.
-3. Explore the repo: stack, package manager, build/test/lint commands, CI,
-   generated files, secret/config paths, deployment surfaces.
-4. Interview the developer, one question at a time, covering at minimum:
-   - repository purpose and primary users/operators
-   - hard invariants that must never break
-   - off-limits paths
-   - what counts as verification ("smallest command that proves a change")
-   - concern detection: persisted data? secrets? IaC? frontend? release flow?
-5. Fill every `<agent: ...>` placeholder in `AGENTS.md` and the starter
-   skills. Keep `AGENTS.md` a router — deep content goes in docs/skills.
-6. For each detected concern with no matching skill, create
-   `.agents/skills/<name>/SKILL.md` (follow the shape of the starter
-   skills) and add a "Load on demand" row in `AGENTS.md`.
-7. Seed `docs/CURRENT_STATE.md` by running `/current-state`.
-8. Mirror any skills/commands you created into each harness dir the same
-   way existing ones are exposed (symlink or copy — check `.agents/bearings.json`).
-9. Run `bearings verify`. Fix every failure. Report remaining warnings to
-   the developer with a recommendation each.
-10. Remove the `## Setup Status` section from `AGENTS.md`.
+1. Read `AGENTS.md` and `.agents/bearings.json`.
+2. Review every recorded Backup File with the developer: read the backup,
+   summarise what it contained, and ask per file whether to merge into the
+   new scaffold, keep parts, or discard. Apply their choice, then remove
+   the resolved backup.
+3. Explore the repo: stack, package manager, canonical install/run/build/
+   test/lint commands, CI, generated paths, secret/config paths, deployment
+   surfaces, project purpose, users/operators, and hard domain/technical
+   constraints. Interview the developer one question at a time for anything
+   the code cannot answer.
+4. Fill only the `AGENTS.md` project-purpose and primary-stack placeholders.
+   Keep `AGENTS.md` a thin router — do not add a skill table, invariants
+   section, or always-on rules block.
+5. Create a project-specific skill only when native skill discovery has no
+   adequate existing match. Every starter skill is bearings-owned — leave
+   them untouched.
+6. Run the `/refresh-repo-map` workflow to initialize `docs/DOMAIN.md`,
+   `docs/ARCHITECTURE.md`, `docs/CODEBASE_MAP.md`, and
+   `docs/diagrams/c4-component.puml`.
+7. Expose any newly created skills into each configured harness using the
+   manifest's existing symlink/copy mode.
+8. Run `bearings verify`. Fix every failure and every warning.
+9. Confirm the run reports zero failures and zero warnings before
+   proceeding.
+10. Remove the `## Setup Required` section from `AGENTS.md` — only after
+    step 9 confirms zero failures and zero warnings.
+11. Run `bearings verify` again and report the completed setup to the
+    developer.
 
 ## Rules
 
-- Do not overwrite developer decisions silently — every merge/discard of a
-  backup is the developer's call.
-- Do not edit `.agents/bearings.json` except where this command requires it.
-- Do not invent invariants — every Hard Invariant line must come from the
-  developer or from clear evidence in the code (cite the path).
-- Re-running this command later is allowed: skip completed steps, focus on
-  drift between docs and reality.
+- Do not overwrite developer decisions silently — every merge/keep/discard
+  of a Backup File is the developer's call.
+- Do not edit `.agents/bearings.json` except where this workflow requires
+  it.
+- Do not change bearings-owned starter commands or skills. The one exception:
+  a reconciliation that records an explicit Merge decision permits applying
+  that Backup File's changes directly to its bearings-owned target.
+- Do not add a skill registry row to `AGENTS.md` — native skill discovery
+  replaces it.
+- Do not invent domain or technical constraints — every stated constraint
+  must come from the developer or from clear evidence in the code (cite
+  the path).
+- Do not remove the `## Setup Required` section before `bearings verify`
+  reports zero failures and zero warnings.
+- Re-running this command later is allowed: skip completed steps and focus
+  on drift between the maps and reality.

package/templates/agents/skills/commit-convention/SKILL.md

@@ -1,35 +1,98 @@
 ---
-description: Use before creating a git commit, writing a commit message, changelog entry, or release-affecting change.
+name: commit-convention
+description: Commit changes through a deterministic commit gate. Use when an agent is about to create a git commit.
 ---
 
-# Commit Convention
+# Commit Gate
 
-## Purpose
+## Project Commands
 
-Keep history searchable and release automation predictable.
+- Format intended files: `<agent: fill during handoff — formatter command accepting explicit file paths>`
+- Fix lint errors in intended files: `<agent: fill during handoff — lint-fix command accepting explicit file paths>`
+- Check lint: `<agent: fill during handoff — complete lint command>`
+- Typecheck: `<agent: fill during handoff — typecheck command or "not configured">`
+- Test suite: `<agent: fill during handoff — complete test-suite command>`
+- Build: `<agent: fill during handoff — build command or "not configured">`
 
-## Triggers
+## Required Workflow
 
-- You are about to commit.
-- You are choosing a commit type, scope, footer, or release note.
+1. Establish the intended change set.
+   - Inspect `git status`, `git diff`, and `git diff --cached`.
+   - The current task defines the commit allowlist; repository dirtiness does not expand it.
+   - Classify every changed hunk as intended or unrelated.
+   - Preserve unrelated staged and unstaged changes exactly.
+   - For a mixed file, proceed only when tools and hunk staging can leave unrelated changes untouched.
+   - Completion: every hunk is classified and the intended changes can be isolated safely.
 
-## Required Workflow
+2. Format and lint-fix the intended files.
+   - Pass explicit intended file paths to each configured tool.
+   - Repository-wide auto-fixes are prohibited.
+   - Reinspect the diff after each command and require unrelated hunks to remain unchanged.
+   - Completion: every intended file is formatted and has no lint errors.
+
+3. Run the quality gates.
+   - Run the complete lint check.
+   - Run typecheck when configured.
+   - Run the complete test suite.
+   - Run the build when configured.
+   - Completion: every configured gate must exit successfully.
+
+4. Review and stage the intended changes.
+   - Reject secrets, debug code, generated noise, and unrelated changes.
+   - Stage explicit intended paths or hunks; `git add .` and `git add -A` are prohibited.
+   - Review `git diff --cached`.
+   - Completion: every staged hunk belongs to the current task.
+
+5. Write the commit message.
+   - Follow the Conventional Commits policy below.
+   - Describe the staged change rather than the broader task or conversation.
+   - Completion: the message satisfies the documented grammar and rules.
+
+6. Create and verify the commit.
+   - Commit without bypassing hooks.
+   - Amend only when the developer explicitly requests it.
+   - Verify the resulting commit hash and message.
+   - Report the commit and any unrelated changes left untouched.
+   - Completion: the commit exists with the intended tree and message.
+
+## Conventional Commits
+
+Use `<type>[optional scope][!]: <imperative summary>`.
 
-1. Inspect `git status` and `git diff` -> stage only intended files.
-2. Choose the commit type and scope -> match the project's release rules.
-3. Write the commit message -> use the required format exactly.
-4. Commit without co-author trailers unless the developer asked for them.
+| Type | Use |
+|---|---|
+| `feat` | New user-visible behavior |
+| `fix` | Defect correction |
+| `docs` | Documentation only |
+| `style` | Formatting with no behavior change |
+| `refactor` | Internal change with no feature or fix |
+| `perf` | Performance improvement |
+| `test` | Tests only |
+| `build` | Build system or dependency changes |
+| `ci` | CI configuration |
+| `chore` | Maintenance not covered above |
+| `revert` | Revert a previous commit |
 
-## Rules
+Message rules:
 
-- Do: use `<agent: fill during handoff — commit message format and allowed types>`.
-- Do not: commit unrelated files, secrets, generated noise, or unverified work.
+- Use a short, imperative summary beginning with lowercase text.
+- Keep the complete subject line at or below 72 characters and omit a trailing period.
+- Use a stable package or subsystem name as the optional scope.
+- Mark breaking changes with `!` and add a `BREAKING CHANGE:` footer.
+- Add a body only when the reason or migration impact is not clear from the subject.
+- Add issue references as footers when applicable.
+- Add co-author or agent attribution only when explicitly requested.
 
-## Verification
+Examples:
 
-- Run `<agent: fill during handoff — pre-commit verification command>` before committing when available.
+- `feat(cli): add copy-mode verification`
+- `fix(adapter): preserve unrelated staged changes`
+- `docs: clarify setup workflow`
+- `refactor(generator)!: replace manifest ownership model`
 
-## References
+## Stop Conditions
 
-- `<agent: fill during handoff — release/changelog config path>` - release semantics.
-- `<agent: fill during handoff — contribution or commit policy path>` - local commit rules.
+- Unsafe change isolation -> report the overlap and create no commit.
+- A required gate fails because of intended changes -> fix it and rerun that gate.
+- A required gate fails for an unrelated or pre-existing reason -> report it and create no commit.
+- A commit hook fails -> treat it as a required gate; keep the hook enabled.

package/templates/agents/skills/defer-work/SKILL.md

@@ -1,4 +1,5 @@
 ---
+name: defer-work
 description: Use when the developer explicitly parks, defers, postpones, skips-for-now, or chooses an interim solution instead of a fuller plan.
 ---
 
@@ -18,7 +19,7 @@ Record intentional "yes, later" work so future agents do not silently build or f
 1. Confirm the deferred item -> get explicit developer approval to record it.
 2. Capture business need, parked approach, reason, and revisit trigger -> make the future decision self-contained.
 3. Create `docs/deferred/DEF-NNN-topic.md` -> assign the next available ID.
-4. Add a row to `docs/deferred/INDEX.md` -> include ID, parked item, revisit trigger, and detail path.
+4. Add a row to `docs/deferred/INDEX.md` -> include ID, postponed item, reason, revisit trigger, and detail path.
 
 ## Rules
 
@@ -32,4 +33,3 @@ Record intentional "yes, later" work so future agents do not silently build or f
 ## References
 
 - `docs/deferred/INDEX.md` - registry of parked work.
-- `docs/conventions/doc-lifecycle.md` - deferred-work lifecycle.

package/templates/agents/skills/recording-decisions/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: recording-decisions
+description: Use when the developer approves a consequential domain or technical decision that needs an ADR.
+---
+
+# Recording Decisions
+
+## Purpose
+
+Turn an approved consequential decision into a durable, discoverable ADR
+without inventing approval or leaving the detail and index out of sync.
+
+## Triggers
+
+- The developer approves a consequential domain or technical decision.
+- An accepted decision must supersede an existing ADR.
+
+## Required Workflow
+
+1. Confirm explicit developer approval and the exact decision scope -> never
+   invent or infer approval.
+2. Read `docs/adr/INDEX.md` and any matching ADRs.
+3. Choose the next four-digit ADR ID.
+4. Create `docs/adr/NNNN-kebab-title.md` with Status, Context, Scope,
+   Decision, Alternatives, Consequences, and Supersession.
+5. If this decision supersedes an existing ADR -> mark the old ADR
+   superseded and cross-link both records in their Supersession sections.
+6. Add or update the row in `docs/adr/INDEX.md` in the same change -> update
+   both the new detail file and the index together.
+7. Validate every path, status, ID, and supersession link before reporting
+   completion.
+
+## Rules
+
+- Do: record only decisions with explicit developer approval.
+- Do: update both `docs/adr/INDEX.md` and the ADR detail file in the same
+  change; never leave one without the other.
+- Do not: invent or infer approval for a decision the developer has not
+  confirmed.
+- Do not: edit implementation code as part of this workflow.
+- Do not: leave the detail file and index inconsistent.
+
+## Verification
+
+- Run `<agent: fill during handoff — docs/link validation command>` when ADR
+  detail or index content changes.
+
+## References
+
+- `docs/adr/INDEX.md` - decision routing registry.
+- `docs/adr/0000-template.md` - ADR detail contract.

package/templates/agents/skills/resurface-deferred-work/SKILL.md

@@ -1,5 +1,6 @@
 ---
-description: Use before building, planning, or designing work that matches an entry in docs/deferred/INDEX.md.
+name: resurface-deferred-work
+description: Use when building, planning, or designing work that matches an entry in docs/deferred/INDEX.md.
 ---
 
 # Resurface Deferred Work
@@ -33,4 +34,3 @@ Prevent agents from silently building over parked decisions without confirming t
 ## References
 
 - `docs/deferred/INDEX.md` - parked-work registry.
-- `docs/conventions/doc-lifecycle.md` - lifecycle for deferred plans.

package/templates/docs/ARCHITECTURE.md

@@ -0,0 +1,37 @@
+# ARCHITECTURE
+
+Answers: how is the system technically shaped? Populated and kept current by `/refresh-repo-map`. Do not hand-edit outside that workflow.
+
+## System Boundary
+
+<agent: fill via /refresh-repo-map - the system and runtime boundary: what is inside versus outside this codebase.>
+
+## Primary Stack
+
+<agent: fill via /refresh-repo-map - primary language, runtime, framework, platform, and package manager.>
+
+## Significant Dependencies
+
+<agent: fill via /refresh-repo-map - architecture-significant dependencies and the role each plays.>
+
+## Components and Dependency Direction
+
+<agent: fill via /refresh-repo-map - major components and the direction dependencies flow between them.>
+
+## Integrations and State Ownership
+
+<agent: fill via /refresh-repo-map - external integrations and which component owns which state.>
+
+## Runtime and Deployment
+
+<agent: fill via /refresh-repo-map - runtime topology and how the system is deployed.>
+
+## Development Environment
+
+<agent: fill via /refresh-repo-map - local prerequisites and canonical install, run, build, test, and lint commands.>
+
+## Architectural Constraints
+
+<agent: fill via /refresh-repo-map - durable technical constraints and links to governing ADRs.>
+
+<!-- repo-map-synced: <agent: fill via /refresh-repo-map> -->

package/templates/docs/CODEBASE_MAP.md

@@ -0,0 +1,33 @@
+# CODEBASE_MAP
+
+Answers: where is today's shipped implementation? Organized by capability and concern, not directory order. Populated and kept current by `/refresh-repo-map`. Do not hand-edit outside that workflow.
+
+## Executable Entry Points
+
+<agent: fill via /refresh-repo-map - the executable entry points into this codebase.>
+
+## Capabilities and Concerns
+
+<agent: fill via /refresh-repo-map - each shipped capability or technical concern and its owning `path#symbol` anchors.>
+
+## Critical Flows
+
+<agent: fill via /refresh-repo-map - critical flow chains where one owner table cannot show the route clearly.>
+
+## Shared Utilities and Infrastructure
+
+<agent: fill via /refresh-repo-map - shared utilities and infrastructure used across capabilities.>
+
+## Interfaces and State
+
+<agent: fill via /refresh-repo-map - interfaces, state, side effects, and external boundaries.>
+
+## Change Hazards
+
+<agent: fill via /refresh-repo-map - change hazards that affect safe routing or proof.>
+
+## Verification Map
+
+<agent: fill via /refresh-repo-map - relevant tests and verification commands per capability.>
+
+<!-- repo-map-synced: <agent: fill via /refresh-repo-map> -->