code-anchored-context 0.2.1 → 0.2.3

package/.agents/skills/code-anchored-context/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-anchored-context
-description: Use central repository context for planning and implementation. Use when starting, changing, reviewing, or documenting behavior-changing work; when checking or updating context/current.md, context/releases/*/initiatives/*, context/programs/*, context/programs/*/planned-initiatives/*, context/backlog/items/*, specs, plans, interface notes, architecture notes, testing notes, delivery notes, infrastructure notes, actionable operations notes, ADRs, backlog, release-doc-notes.md; when promoting planned initiatives during release transitions; or when deciding whether docs/ should be left untouched.
+description: Use central repository context for planning and implementation. Use when starting, changing, reviewing, or documenting behavior-changing work; when checking or updating context/current.md, context/releases/*/initiatives/*, context/programs/*, context/programs/*/planned-initiatives/*, context/backlog/items/*, specs, plans, interface notes, architecture notes, testing notes, delivery notes, infrastructure notes, actionable operations notes, ADRs, backlog, release-doc-notes.md; when promoting planned initiatives during release transitions; or when deciding whether reference/ should be left untouched.
 ---
 
 # Code-Anchored Context
@@ -59,8 +59,8 @@ effort, link it to the relevant program.
 ### 4) Create An Initiative When Needed
 
 Create a new initiative for non-trivial behavior changes, cross-project
-work, release-significant work, or anything likely to need future product
-documentation.
+work, release-significant work, or anything likely to need future reference
+updates.
 
 Use `context/_templates/initiative/` as the source. Copy it to:
 
@@ -164,7 +164,7 @@ Use these files as the standard map:
   observability, failure modes, rollback, repair, and support tooling
 - `backlog.md`: work slices and implementation progress
 - `decisions/ADR-*.md`: meaningful choices and their consequences
-- `release-doc-notes.md`: product-documentation impact to review at release
+- `release-doc-notes.md`: reference impact to review at release
 
 Not every initiative needs every file. Mark a file as not applicable or omit
 it after copying the template when it genuinely does not apply.
@@ -175,15 +175,14 @@ settled truth lives. Promote stable conclusions into `spec.md`,
 `infrastructure.md`, `operations.md` when actionable, `backlog.md`, ADRs, or
 `release-doc-notes.md` as appropriate.
 
-### 9) Preserve The Docs Boundary
+### 9) Preserve The Reference Boundary
 
-Do not edit `docs/` as part of normal feature work, bug fixes,
+Do not edit `reference/` as part of normal feature work, bug fixes,
 refactors, or planning. Instead, update the initiative's
 `release-doc-notes.md`.
 
-Only update `docs/` when a human explicitly asks for release
-documentation work, a specific page update, or a demonstrable documentation
-fix.
+Only update `reference/` when a human explicitly asks for release reference
+work, a specific page update, or a demonstrable reference fix.
 
 ## Knowledge Ownership
 
@@ -205,5 +204,5 @@ Before finishing behavior-changing work:
 - Any changed behavior, interface, architecture, testing, delivery,
   infrastructure, actionable operations, or backlog state was reflected in the
   initiative when appropriate.
-- Future product-documentation impact was captured in `release-doc-notes.md`.
-- `docs/` was left untouched unless explicitly requested.
+- Future reference impact was captured in `release-doc-notes.md`.
+- `reference/` was left untouched unless explicitly requested.

package/AGENTS.md

@@ -14,20 +14,21 @@ For behavior-changing work, use the repo-wide skill at
 Keep initiative knowledge centralized under `context/`; area
 `AGENTS.md` files should point there rather than copying active plans.
 
-## Docs Authoring
+## Reference Authoring
 
-### When To Edit `docs/`
+### When To Edit `reference/`
 
-Do not edit `docs/` as a side effect of feature work, bug fixes,
-refactors, or other code changes. Docs in this model are release-anchored:
+Do not edit `reference/` as a side effect of feature work, bug fixes,
+refactors, or other code changes. Reference material in this model is
+release-anchored:
 they describe the behavior of a specific release tag, not the partial state of
 a working branch.
 
-Touch `docs/` only when:
+Touch `reference/` only when:
 
-- A human explicitly asks you to refresh the docs for a release, typically
+- A human explicitly asks you to refresh reference for a release, typically
   after a release tag is cut and QA has signed off.
-- A human explicitly asks you to create or refresh baseline documentation for
+- A human explicitly asks you to create or refresh baseline reference for
   an existing project.
 - A human explicitly asks you to update a specific page.
 - A human asks you to fix a demonstrable error in an existing page, such as a
@@ -35,20 +36,20 @@ Touch `docs/` only when:
 
 If you are unsure whether the request is one of these, ask before editing.
 
-If a project has documentation that intentionally follows a different cadence,
+If a project has reference material that intentionally follows a different cadence,
 document that exception in the area's README and in
-`docs/_authoring/areas/`.
+`reference/_authoring/areas/`.
 
 ### Where The Authoring Guidance Lives
 
-All documentation workflow, per-area authoring guides, and domain terminology
-live under [`docs/_authoring/`](docs/_authoring/). Start
-with [`docs/_authoring/README.md`](docs/_authoring/README.md).
+All reference workflow, per-area authoring guides, and domain terminology
+live under [`reference/_authoring/`](reference/_authoring/). Start
+with [`reference/_authoring/README.md`](reference/_authoring/README.md).
 
-If you are refreshing docs, the per-area guides in
-[`docs/_authoring/areas/`](docs/_authoring/areas/) tell you
+If you are refreshing reference, the per-area guides in
+[`reference/_authoring/areas/`](reference/_authoring/areas/) tell you
 what matters and what to ignore for each area.
 
 `AGENTS.md` files stay lean. They are for coding conventions and agent
-restrictions, not detailed documentation guidance. If you have doc rules to
+restrictions, not detailed reference guidance. If you have reference rules to
 add, add them under `_authoring/`.

package/README.md

@@ -1,7 +1,7 @@
 # Code-Anchored Context Template
 
 This repository is a reusable starting point for keeping repository-local
-working context and release-anchored product documentation close to the
+working context and release-anchored reference close to the
 code they describe.
 
 It separates two kinds of truth:
@@ -9,7 +9,7 @@ It separates two kinds of truth:
 | Folder | Meaning | Updated when |
 | --- | --- | --- |
 | `context/` | What the team is planning, building, deciding, validating, shipping, hosting, deferring, and learning. | During normal development. |
-| `docs/` | What the product does as of a known release or tag. | Only during explicit documentation refresh work. |
+| `reference/` | What the system does as of a known release or explicit baseline. | Only during explicit reference refresh work. |
 
 The goal is to give humans and AI agents enough structured context to change a
 codebase without relying on chat history, tribal memory, or scattered planning
@@ -21,8 +21,8 @@ notes.
 - `.agents/skills/code-anchored-context/SKILL.md` for the recurring
   working-context workflow.
 - `context/` with terminology, release context, backlog/program structure,
-  initiative templates, and a human-readable article and brief.
-- `docs/` with a generic release-anchored documentation workflow,
+  initiative templates, and release-documentation notes.
+- `reference/` with a generic release-anchored reference workflow,
   authoring guide structure, and area/page templates.
 
 ## Adopting This In A Project
@@ -39,7 +39,7 @@ Useful options:
 
 ```bash
 npx code-anchored-context init --dry-run
-npx code-anchored-context init --no-docs
+npx code-anchored-context init --no-reference
 npx code-anchored-context init --target ../existing-project
 ```
 
@@ -54,10 +54,10 @@ Manual adoption still works:
 2. Replace `PROJECT_NAME` placeholders with the project name.
 3. Set the first active release in `context/current.md`.
 4. Add or revise area-specific `AGENTS.md` files so they point back to
-   `context/` and `docs/_authoring/`.
-5. Create `docs/_authoring/areas/<area>.md` for each documented
+   `context/` and `reference/_authoring/`.
+5. Create `reference/_authoring/areas/<area>.md` for each referenced
    product or code area.
-6. Keep product or domain-specific documentation out of this template repo.
+6. Keep product or domain-specific reference content out of this template repo.
 
 ## Publishing The Package
 
@@ -78,8 +78,8 @@ npx @your-scope/code-anchored-context init
 
 ## Working Rule
 
-Working context can evolve with the branch. Product docs should
+Working context can evolve with the branch. Reference material should
 stay stable and release-accurate. When behavior changes during development,
-record future documentation impact in the relevant initiative's
-`release-doc-notes.md`; refresh `docs/` only when that work is
+record future reference impact in the relevant initiative's
+`release-doc-notes.md`; refresh `reference/` only when that work is
 explicitly requested.

package/bin/code-anchored-context.js

@@ -54,7 +54,7 @@ async function main() {
     dryRun: args.dryRun
   });
 
-  await installer.init({ includeDocs: args.docs });
+  await installer.init({ includeReference: args.reference });
 }
 
 function parseArgs(argv) {
@@ -65,7 +65,7 @@ function parseArgs(argv) {
     release: defaultRelease,
     force: false,
     dryRun: false,
-    docs: true,
+    reference: true,
     help: false,
     version: false
   };
@@ -95,8 +95,8 @@ function parseArgs(argv) {
       continue;
     }
 
-    if (arg === '--no-docs') {
-      options.docs = false;
+    if (arg === '--no-reference') {
+      options.reference = false;
       continue;
     }
 
@@ -170,7 +170,7 @@ Options:
   --target <path>          Project root to install into. Defaults to cwd.
   --project-name <name>   Name used to replace PROJECT_NAME placeholders.
   --release <slug>        Initial release slug. Defaults to ${defaultRelease}.
-  --no-docs               Skip the docs/ starter files.
+  --no-reference          Skip the reference/ starter files.
   --force                 Replace existing generated directories.
   --dry-run               Show planned changes without writing files.
   -h, --help              Show help.
@@ -178,7 +178,7 @@ Options:
 
 Examples:
   npx code-anchored-context init --project-name "My App"
-  npx code-anchored-context init --release v1_0_0 --no-docs
+  npx code-anchored-context init --release v1_0_0 --no-reference
 `);
 }
 
@@ -215,7 +215,7 @@ class Installer {
     this.agentsFilePath = path.join(targetRoot, 'AGENTS.md');
   }
 
-  async init({ includeDocs }) {
+  async init({ includeReference }) {
     await this.ensureDirectory(this.targetRoot);
 
     await this.installAgentsFile();
@@ -223,10 +223,10 @@ class Installer {
     await this.copyTemplatePath('context', 'context');
     await this.renameReleasePaths();
 
-    if (includeDocs) {
-      await this.copyTemplatePath('docs', 'docs');
+    if (includeReference) {
+      await this.copyTemplatePath('reference', 'reference');
     } else {
-      this.note('skip docs/ (--no-docs)');
+      this.note('skip reference/ (--no-reference)');
     }
 
     this.printSummary();

package/context/AGENTS.md

@@ -14,7 +14,7 @@ only when they are actionable runtime, support, observability, rollback, or
 repair context.
 
 `context/` describes what is being planned, built, debated, or validated.
-`docs/` describes what has shipped for a release.
+`reference/` describes what has shipped for a release.
 
 ## Editing Rules
 
@@ -22,9 +22,9 @@ repair context.
   planned initiatives, release initiatives, backlog items, and promotion.
 - Keep initiative knowledge centralized here. Area `AGENTS.md` files may point
   here, but they should not duplicate initiative content.
-- Do not move in-progress plans into `docs/`.
+- Do not move in-progress plans into `reference/`.
 - Use `release-doc-notes.md` inside an initiative to capture what may need to
-  become product documentation later.
+  become reference later.
 - Create initiatives from `context/_templates/initiative/`.
 - Create durable multi-release programs from `context/_templates/program/`.
 - Create scoped future program work from

package/context/README.md

@@ -6,7 +6,7 @@ repository.
 Use it for specs, interface notes, architecture notes, testing notes, delivery
 notes, infrastructure notes, actionable operations notes, ADRs, backlog items,
 implementation plans, and release-documentation notes. Do not use
-`docs/` for in-progress development planning.
+`reference/` for in-progress development planning.
 
 ## Start Here
 
@@ -20,17 +20,17 @@ implementation plans, and release-documentation notes. Do not use
   shape for scoped program work outside the current release.
 - `_templates/release-context/` contains the standard release folder shell.
 
-## Relationship To docs/
+## Relationship To reference/
 
-`context/` and `docs/` serve different jobs:
+`context/` and `reference/` serve different jobs:
 
 | Folder | Meaning | Updated when |
 | --- | --- | --- |
 | `context/` | What we are planning, building, deciding, or validating. | During normal development. |
-| `docs/` | What the product does as of a release or tag. | Only during explicit documentation refresh work. |
+| `reference/` | What the system does as of a release, tag, or explicit baseline. | Only during explicit reference refresh work. |
 
-Working context can feed release documentation, but it is not product
-documentation. Capture that bridge in each initiative's
+Working context can feed release reference, but it is not accepted
+reference. Capture that bridge in each initiative's
 `release-doc-notes.md`.
 
 ## Core Model
@@ -190,7 +190,7 @@ Required for most initiatives:
 | `plan.md` | Working alignment space for humans and agents; rough notes, questions, options, and points to promote. |
 | `spec.md` | What the system should do and which behavior is in or out. |
 | `backlog.md` | What is changing now, sliced into trackable work. |
-| `release-doc-notes.md` | Product documentation impact to review at release time. |
+| `release-doc-notes.md` | Reference impact to review at release time. |
 
 Use when relevant:
 
@@ -246,8 +246,8 @@ When changing behavior, agents should:
    behavior changes that do not belong to an existing initiative.
 7. Create or update a program planned initiative when future scoped work is
    clear but belongs outside the current release.
-8. Record future product-doc impact in `release-doc-notes.md`, not in
-   `docs/`, unless a human explicitly asks for documentation refresh.
+8. Record future reference impact in `release-doc-notes.md`, not in
+   `reference/`, unless a human explicitly asks for reference refresh.
 
 The key rule for planning is:
 

package/context/_templates/initiative/README.md

@@ -17,7 +17,7 @@ produce.
 - Tests or verification: `path/to/...`
 - Delivery, CI/CD, build, or artifacts: `path/to/...`
 - Infrastructure, IaC, or environment config: `path/to/...`
-- Docs or release notes: `path/to/...`
+- Reference or release notes: `path/to/...`
 
 Remove entries that do not apply and add the real paths. Prefer naming the
 delivery concern over assuming a specific folder layout.
@@ -59,5 +59,5 @@ support, observability, rollback, or repair context.
   Promote settled conclusions into the stable initiative files.
 - Update `release-doc-notes.md` when shipped behavior or product-facing
   behavior changes.
-- Do not update `docs/` from this initiative unless a human
-  explicitly asks for release documentation work.
+- Do not update `reference/` from this initiative unless a human
+  explicitly asks for release reference work.

package/context/_templates/initiative/plan.md

@@ -18,7 +18,7 @@ initiative files:
   repair notes
 - `backlog.md` for executable work items
 - `decisions/ADR-*.md` for durable decisions
-- `release-doc-notes.md` for future product-documentation impact
+- `release-doc-notes.md` for future reference impact
 
 ## Current Alignment
 
@@ -54,4 +54,4 @@ the canonical initiative files.
 - [ ] Move multi-release context into `context/programs/`
 - [ ] Move isolated deferred work into `context/backlog/items/`
 - [ ] Move durable decisions into `decisions/`
-- [ ] Move product-documentation impact into `release-doc-notes.md`
+- [ ] Move reference impact into `release-doc-notes.md`

package/context/_templates/initiative/release-doc-notes.md

@@ -1,20 +1,20 @@
 # Release Doc Notes
 
-Use this file to capture product-documentation impact while development is
-in progress. At release time, these notes help refresh `docs/`
+Use this file to capture reference impact while development is
+in progress. At release time, these notes help refresh `reference/`
 against the final shipped behavior.
 
-Do not edit `docs/` from normal development work unless a human
-explicitly asks for a documentation refresh or a specific documentation fix.
+Do not edit `reference/` from normal development work unless a human
+explicitly asks for a reference refresh or a specific reference fix.
 
 ## Product Behavior Changes
 
 - None yet.
 
-## Candidate Docs Areas
+## Candidate Reference Areas
 
-- `docs/<Area>/README.md`
-- `docs/<Area>/features/<feature>.md`
+- `reference/<Area>/README.md`
+- `reference/<Area>/features/<feature>.md`
 
 ## QA Or Support Notes
 
@@ -29,7 +29,6 @@ ship.
 ## Release-Time Checklist
 
 - [ ] Compare this initiative against the final shipped code.
-- [ ] Update the relevant product documentation only after release-doc work
+- [ ] Update the relevant reference only after release-doc work
       is explicitly requested.
-- [ ] Add the release row if the documentation workflow requires it.
-
+- [ ] Add the release row if the reference workflow requires it.

package/context/_templates/planned-initiative/README.md

@@ -19,7 +19,7 @@ and what outcome it should produce.
 - Tests or verification: `path/to/...`
 - Delivery, CI/CD, build, or artifacts: `path/to/...`
 - Infrastructure, IaC, or environment config: `path/to/...`
-- Docs or release notes: `path/to/...`
+- Reference or release notes: `path/to/...`
 
 Remove entries that do not apply and add the real paths. Prefer naming the
 delivery concern over assuming a specific folder layout.

package/context/_templates/planned-initiative/plan.md

@@ -37,4 +37,4 @@ Describe the current agreed future direction.
 - [ ] Move actionable runtime/support concerns into `operations.md`
 - [ ] Move executable future work into `backlog.md`
 - [ ] Move durable program decisions into the parent program's `decisions/`
-- [ ] Move product-documentation impact into `release-doc-notes.md`
+- [ ] Move reference impact into `release-doc-notes.md`

package/context/_templates/planned-initiative/release-doc-notes.md

@@ -1,20 +1,20 @@
 # Release Doc Notes
 
-Use this file to capture expected product-documentation impact while future
+Use this file to capture expected reference impact while future
 work is being planned. When the planned initiative is promoted and later
 implemented, compare these notes against the final shipped behavior.
 
-Do not edit `docs/` from normal development work unless a human
-explicitly asks for a documentation refresh or a specific documentation fix.
+Do not edit `reference/` from normal development work unless a human
+explicitly asks for a reference refresh or a specific reference fix.
 
 ## Expected Product Behavior Changes
 
 - None yet.
 
-## Candidate Docs Areas
+## Candidate Reference Areas
 
-- `docs/<Area>/README.md`
-- `docs/<Area>/features/<feature>.md`
+- `reference/<Area>/README.md`
+- `reference/<Area>/features/<feature>.md`
 
 ## QA Or Support Notes
 
@@ -25,4 +25,3 @@ explicitly asks for a documentation refresh or a specific documentation fix.
 Record details that were considered but should not be documented because
 they are internal implementation details, temporary scaffolding, or might not
 ship.
-

package/context/terminology.md

@@ -9,7 +9,7 @@ backlog items, ADRs, agent summaries, and release-transition work.
 | Term | Meaning |
 | --- | --- |
 | `context/` | Working context: plans, specs, ADRs, implementation notes, delivery-surface context, future scope, and release-documentation notes. |
-| `docs/` | Released product documentation. It describes shipped behavior for a release/tag and is not edited during normal development work. |
+| `reference/` | Accepted reference. It describes shipped or baseline behavior for a release/tag and is not edited during normal development work. |
 | `context/current.md` | Pointer to the current active release context. Updating this is a release transition. |
 | `context/releases/<version>/` | Release-scoped working context for one version. |
 | `context/programs/` | Durable multi-release working context. |
@@ -60,7 +60,7 @@ both readable Markdown for agents and renderable visual context for humans.
 | `infrastructure.md` | Stable description of environment shape, IaC, resources, networking, identity, storage, secrets, and environment dependencies. |
 | `operations.md` | Optional actionable runtime support context: observability, failure modes, rollback, repair, support procedures, and tooling. |
 | `backlog.md` | Trackable work items for the containing initiative or program. |
-| `release-doc-notes.md` | Notes for future product documentation refresh work. This is the bridge to `docs/`. |
+| `release-doc-notes.md` | Notes for future reference refresh work. This is the bridge to `reference/`. |
 | ADR | Architecture Decision Record. Use for durable decisions and tradeoffs. |
 | `brief.html` | Optional human-friendly presentation layer. |
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "code-anchored-context",
-  "version": "0.2.1",
-  "description": "Install repo-local agent context, release initiatives, and release-anchored docs scaffolding into an existing project.",
+  "version": "0.2.3",
+  "description": "Install repo-local agent context, release initiatives, and release-anchored reference scaffolding into an existing project.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "context/releases/v0_1_0/backlog.md",
     "context/releases/v0_1_0/initiatives/.gitkeep",
     "context/terminology.md",
-    "docs/",
+    "reference/",
     "bin/",
     "README.md",
     "LICENSE"
@@ -37,6 +37,6 @@
     "ai",
     "documentation",
     "working-context",
-    "docs"
+    "reference"
   ]
 }

package/reference/README.md

@@ -0,0 +1,62 @@
+# Reference
+
+This folder holds release-anchored reference material for PROJECT_NAME.
+
+Reference describes accepted system behavior for a known release, tag, or
+explicit baseline. It is not the place for in-progress planning,
+implementation notes, or draft architecture decisions. Put that work in
+`context/`.
+
+## Start Here
+
+- `releases/index.md` records release or baseline reference refreshes.
+- `_authoring/README.md` explains how humans and agents should author
+  reference material.
+- `_authoring/workflow.md` defines when reference material is refreshed and what
+  belongs here.
+- `_authoring/areas/` contains per-area authoring guidance.
+
+## Standard Layout
+
+```text
+reference/
+  README.md
+  releases/
+    index.md
+  _authoring/
+    README.md
+    workflow.md
+    terminology.md
+    areas/
+      <area>.md
+  _templates/
+    area/
+      README.md
+      features/
+        feature-template.md
+  <Area>/
+    README.md
+    features/
+      <feature>.md
+```
+
+Every documented area should have:
+
+- a high-level `README.md` that explains the area's purpose and architecture
+- one page per feature under `features/`
+- an authoring guide under `reference/_authoring/areas/`
+
+## Contributing
+
+- Refresh reference material only when explicitly asked.
+- For existing projects with little or no reference material, create
+  baseline reference only when explicitly asked; otherwise document touched
+  behavior during future release refreshes.
+- Write for non-developer technical readers unless the project states
+  otherwise.
+- Write from behavior outward: product-readable first, technically anchored
+  where details affect shipped behavior, operations, or support.
+- Describe behavior, inputs, outputs, permissions, errors, business rules, and
+  operational expectations in domain language.
+- Prefer Mermaid diagrams for flows, architecture, and relationships.
+- Add release refreshes to `reference/releases/index.md`.

package/{docs → reference}/_authoring/README.md

@@ -1,14 +1,14 @@
-# Docs Authoring Guide
+# Reference Authoring Guide
 
-This subtree owns all guidance for authoring and refreshing the documentation
-under `docs/`. Humans and agents both read from here to know how
-documentation is structured, when it is refreshed, what belongs in each area,
+This subtree owns all guidance for authoring and refreshing the reference
+under `reference/`. Humans and agents both read from here to know how
+reference is structured, when it is refreshed, what belongs in each area,
 and which domain terminology to use.
 
 ## Start Here
 
-- [`workflow.md`](workflow.md) explains how docs are versioned, refreshed, and
-  structured.
+- [`workflow.md`](workflow.md) explains how reference is versioned,
+  refreshed, and structured.
 - [`terminology.md`](terminology.md) holds project-specific domain language.
 - [`areas/`](areas/) contains one file per documented area, covering feature
   inventory, code orientation, conventions, and what matters at release time.
@@ -18,14 +18,14 @@ and which domain terminology to use.
 Create one authoring guide per documented area:
 
 ```text
-docs/_authoring/areas/<area-slug>.md
+reference/_authoring/areas/<area-slug>.md
 ```
 
 Each area guide should identify:
 
 - the source locations that own the behavior, such as product code,
   interfaces, tests, CI/CD, generated artifacts, infrastructure, or config
-- the docs root under `docs/`
+- the reference root under `reference/`
 - feature pages that should exist
 - behavior that matters at release time
 - changes to ignore, such as pure refactors or test-only edits
@@ -36,7 +36,7 @@ Use [`areas/_template.md`](areas/_template.md) when adding a new area guide.
 ## Relationship To `AGENTS.md`
 
 Area `AGENTS.md` files may point here, but they should not copy the detailed
-documentation workflow. Keep authoring rules in this subtree so the guidance
+reference workflow. Keep authoring rules in this subtree so the guidance
 has one source of truth.
 
 ## Contributing

package/{docs → reference}/_authoring/areas/README.md

@@ -5,10 +5,10 @@ This folder contains one authoring guide per documented area.
 Create a guide from `_template.md` when adding a documentation area:
 
 ```text
-docs/_authoring/areas/<area-slug>.md
+reference/_authoring/areas/<area-slug>.md
 ```
 
-Each guide should help a human or agent refresh docs from a release diff
+Each guide should help a human or agent refresh reference from a release diff
 without rediscovering the area's structure from scratch.
 
 ## Current Area Guides

package/{docs → reference}/_authoring/areas/_template.md

@@ -4,7 +4,7 @@
 
 - Source orientation: `path/to/runtime-or-product-code`, `path/to/contracts`,
   `path/to/tests`, `path/to/ci-or-delivery`, `path/to/infra-or-config`
-- Docs root: `docs/<Area>/`
+- Reference root: `reference/<Area>/`
 - Owner or reviewer: TBD
 
 Describe what this area owns and what it intentionally does not own.
@@ -18,9 +18,9 @@ operational expectations without private implementation detail.
 
 ## Feature Inventory
 
-| Feature | Docs page | Notes |
+| Feature | Reference page | Notes |
 | --- | --- | --- |
-| TBD | `docs/<Area>/features/<feature>.md` | TBD |
+| TBD | `reference/<Area>/features/<feature>.md` | TBD |
 
 ## What Matters At Release Time
 
@@ -57,9 +57,9 @@ known gaps, and questions that should not yet appear in product-facing docs.
 
 ## Terminology
 
-List area-specific terms or link to `docs/_authoring/terminology.md`.
+List area-specific terms or link to `reference/_authoring/terminology.md`.
 
 ## Cross-Links
 
-List related areas and when docs should cross-link instead of duplicating
+List related areas and when reference should cross-link instead of duplicating
 behavior.

package/{docs → reference}/_authoring/terminology.md

@@ -2,7 +2,7 @@
 
 Use this file to define the domain language that documentation should use.
 
-Docs should translate code-level names into reader-facing domain
+Reference should translate code-level names into reader-facing domain
 terms when those differ. The goal is consistency for QA, product, support,
 operators, and future agents.
 

package/{docs → reference}/_authoring/workflow.md

@@ -1,95 +1,96 @@
-# Docs Workflow
+# Reference Workflow
 
-This file defines how documentation is versioned, refreshed, and structured
+This file defines how reference material is versioned, refreshed, and structured
 across the repo. It applies to all documented areas; area-specific guidance
 lives in [`areas/`](areas/).
 
-## When Docs Get Edited
+## When Reference Gets Edited
 
-Doc refresh is an explicit, on-request activity, not a side effect of code
-work. Humans or agents touch `docs/` only when:
+Reference refresh is an explicit, on-request activity, not a side effect of
+code work. Humans or agents touch `reference/` only when:
 
 - A human explicitly asks for a release-time refresh, typically after the
   release tag is cut and QA has signed off.
-- A human explicitly asks for baseline documentation for an existing project,
-  such as "document this repo baseline" or "create initial docs for the current
+- A human explicitly asks for baseline reference for an existing project, such
+  as "document this repo baseline" or "create initial reference for the current
   system."
 - A human explicitly asks to update a specific page.
 - A human asks to fix a demonstrable error in an existing page, such as a
   broken link or factual inaccuracy.
 
-Do not update docs as part of a feature PR, bug fix, refactor, or dependency
-bump. Mid-stream commits are partial work; "feature complete" is only
+Do not update reference as part of a feature PR, bug fix, refactor, or
+dependency bump. Mid-stream commits are partial work; "feature complete" is only
 well-defined once the release is accepted.
 
-Agents: if you are working on a code change and notice a doc that looks
+Agents: if you are working on a code change and notice reference material that looks
 outdated, leave it alone. Flag the staleness in your summary or add it to the
-initiative's `release-doc-notes.md`, but do not edit the doc as part of the
-current change unless explicitly asked.
+initiative's `release-doc-notes.md`, but do not edit the reference material as
+part of the current change unless explicitly asked.
 
-## Docs Modes
+## Reference Modes
 
-There are two valid ways to introduce or maintain `docs/`.
+There are two valid ways to introduce or maintain `reference/`.
 
-### Baseline Docs
+### Baseline Reference
 
 Use this mode only when a human explicitly asks to document the current system
 as a starting point. This is common when adopting the template in an existing
-project that has little or no product documentation.
+project that has little or no reference material.
 
 When creating a baseline:
 
 1. Confirm the scope: whole repo, one product area, one feature family, or one
    operational surface.
 2. Create or update the matching area guide under
-   `docs/_authoring/areas/` before writing product-facing pages.
+   `reference/_authoring/areas/` before writing reference pages.
 3. Document stable, currently accepted behavior from the current branch,
    current tag, or explicit reference point named by the human.
 4. Prefer broad, accurate coverage over exhaustive implementation detail.
-5. Record the baseline reference in `docs/releases/index.md`. If
+5. Record the baseline reference in `reference/releases/index.md`. If
    there is no release tag yet, use the commit, branch, date, or human-named
    baseline label that was used as the source.
-6. Leave uncertain or future behavior out of `docs/`. Capture open
+6. Leave uncertain or future behavior out of `reference/`. Capture open
    questions in `context/` or in the area authoring guide.
 
-Baseline docs are a snapshot of the system as adopted; they are not a promise
-that every undocumented behavior is unimportant.
+Baseline reference is a snapshot of the system as adopted; it is not a
+promise that every undocumented behavior is unimportant.
 
-### Release-Forward Docs
+### Release-Forward Reference
 
 Use this mode when the team chooses not to create a full baseline. In this
-mode, `docs/` may start sparse. Agents capture documentation impact
-in initiative `release-doc-notes.md` during development, then update product
-docs only at explicit release-refresh time.
+mode, `reference/` may start sparse. Agents capture reference impact in
+initiative `release-doc-notes.md` during development, then update reference
+only at explicit release-refresh time.
 
-This is valid when a full baseline would be too expensive. The documentation
+This is valid when a full baseline would be too expensive. The reference
 becomes complete incrementally around behavior the team changes and releases.
 
 ## Cadence And Versioning
 
-Docs live under `docs/`. After any explicit baseline pass, they are
-refreshed once per release, at git-tag time, after release acceptance. Release
-docs are anchored to the release tag; the docs at tag `release/v1_2_3`
-describe the behavior of that release.
+Reference lives under `reference/`. After any explicit baseline pass, it is
+refreshed once per release, at git-tag time, after release acceptance.
+Reference is anchored to the release tag; reference at tag `release/v1_2_3`
+describes the behavior of that release.
 
 Default tag names follow the convention `release/vMAJOR_MINOR_PATCH` and match
 the release branch name. If a project uses a different release convention,
 document it here before the first refresh. If the first documentation pass is
 a baseline without a tag, record the baseline reference in
-`docs/releases/index.md`.
+`reference/releases/index.md`.
 
 ## Audience
 
-Docs are written for non-developer technical readers by default: QA, product
-owners, solution owners, support engineers, customer engineers, or operators.
-Adjust this only when the project explicitly defines a different audience.
+Reference is written for non-developer technical readers by default: QA,
+product owners, solution owners, support engineers, customer engineers, or
+operators. Adjust this only when the project explicitly defines a different
+audience.
 
 - Describe behavior, inputs, outputs, permissions, error conditions, and
   business rules in domain language.
 - Avoid code snippets, private type names, SQL, and framework jargon unless
   the concept has no plain-language equivalent.
-- For readers who need more depth than the docs provide, link to the source
-  rather than replicating the implementation in prose.
+- For readers who need more depth than the reference provides, link to the
+  source rather than replicating the implementation in prose.
 
 ## Writing Focus
 
@@ -100,10 +101,10 @@ or business process can observe. Add technical detail only when it affects
 released behavior, configuration, permissions, data, integrations, errors,
 support, operations, or auditability.
 
-Docs should be product-readable first and technically anchored
-second. They can feed release notes, but they are more durable than release notes:
-release notes summarize what changed, while `docs/` describes what
-the accepted system does as of a release or baseline.
+Reference should be product-readable first and technically anchored second. It
+can feed release notes, but it is more durable than release notes: release
+notes summarize what changed, while `reference/` describes what the accepted
+system does as of a release or baseline.
 
 Use progressive depth:
 
@@ -127,7 +128,7 @@ Every documented area has two layers:
 Standard per-area layout:
 
 ```text
-docs/<Area>/
+reference/<Area>/
   README.md
   features/
     <feature>.md
@@ -158,29 +159,29 @@ Preferred diagram types:
 Keep diagrams small enough to read. If a diagram needs more than about 15 nodes
 or steps, simplify it or split it.
 
-## Feature Docs Cover The Full Vertical
+## Feature Reference Covers The Full Vertical
 
-A feature doc should describe the full behavior path the feature touches:
+A feature reference page should describe the full behavior path the feature touches:
 entry point, important services or processes, data stored or read, external
 systems, permissions, validation, errors, and operational expectations.
 
-If a feature spans multiple areas, place the doc in the area that owns the
+If a feature spans multiple areas, place the page in the area that owns the
 user-facing or operator-facing entry point. Cross-link from the other areas.
 
-## Release-Time Doc Refresh
+## Release-Time Reference Refresh
 
-When invoked to refresh docs for a release:
+When invoked to refresh reference for a release:
 
 1. Work from the diff `<previous-release-tag>..HEAD`, scoped to one area at a
    time.
-2. Read the matching area guide in `docs/_authoring/areas/`.
+2. Read the matching area guide in `reference/_authoring/areas/`.
 3. Read relevant initiative `release-doc-notes.md` files under
    `context/releases/<release>/initiatives/`.
 4. Update the area's `README.md` if the high-level picture changed.
 5. Update feature pages for behavior that changed.
 6. Ignore pure refactors, internal renames, test-only changes, formatting,
    lint fixes, and dependency bumps with no behavior change.
-7. Append one row to `docs/releases/index.md`.
+7. Append one row to `reference/releases/index.md`.
 
 ## Source Order
 
@@ -189,12 +190,12 @@ source inspection:
 
 1. Previous release tag to current release diff.
 2. Relevant initiative `release-doc-notes.md` files.
-3. Matching area guide under `docs/_authoring/areas/`.
-4. Existing product documentation.
+3. Matching area guide under `reference/_authoring/areas/`.
+4. Existing reference.
 5. Source code, tests, config, CI/CD, infrastructure, and generated artifacts
    only as needed to verify shipped behavior.
 
-For baseline documentation, start from the explicit baseline scope and
+For baseline reference, start from the explicit baseline scope and
 reference point named by the human. If no reference is named, use the current
 working tree and say so in the release index row.
 

package/{docs → reference}/releases/index.md

@@ -1,9 +1,9 @@
-# Release Docs Index
+# Reference Release Index
 
 One row per tagged release. Tag names default to `release/vMAJOR_MINOR_PATCH`
 unless the project documents a different convention.
 
-Docs at a given tag describe the behavior of that release.
+Reference at a given tag describes the behavior of that release.
 
 | Tag | Date | Areas refreshed | Owner | Summary |
 | --- | --- | --- | --- | --- |

package/docs/.order

@@ -1,2 +0,0 @@
-Welcome
-releases

package/docs/Welcome.md

@@ -1,48 +0,0 @@
-# PROJECT_NAME Docs
-
-Welcome to the release-anchored documentation for PROJECT_NAME.
-
-This folder describes shipped behavior for a known release or tag. It is not
-the place for in-progress feature planning, implementation notes, or draft
-architecture decisions. Put that work in `context/`.
-
-## How These Docs Are Organized
-
-```text
-docs/
-  .order
-  Welcome.md
-  releases/
-    index.md
-  _authoring/
-    README.md
-    workflow.md
-    terminology.md
-    areas/
-      <area>.md
-  <Area>/
-    README.md
-    features/
-      <feature>.md
-```
-
-Every documented area should have:
-
-- a high-level `README.md` that explains the area's purpose and architecture
-- one page per feature under `features/`
-- an authoring guide under `docs/_authoring/areas/`
-
-## Contributing
-
-- Refresh docs only when explicitly asked.
-- For existing projects with no docs, create baseline documentation only when
-  explicitly asked; otherwise document touched behavior during future release
-  refreshes.
-- Write for non-developer technical readers unless the project states
-  otherwise.
-- Write from behavior outward: product-readable first, technically anchored
-  where details affect shipped behavior, operations, or support.
-- Describe behavior, inputs, outputs, permissions, errors, business rules, and
-  operational expectations in domain language.
-- Prefer Mermaid diagrams for flows, architecture, and relationships.
-- Add release refreshes to `docs/releases/index.md`.