code-anchored-context 0.2.0 → 0.2.2

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 product-docs/ should be left untouched.
 ---
 
 # Code-Anchored Context
@@ -175,13 +175,13 @@ 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 Product Docs Boundary
 
-Do not edit `docs/` as part of normal feature work, bug fixes,
+Do not edit `product-docs/` 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
+Only update `product-docs/` when a human explicitly asks for release
 documentation work, a specific page update, or a demonstrable documentation
 fix.
 
@@ -206,4 +206,4 @@ Before finishing behavior-changing work:
   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.
+- `product-docs/` was left untouched unless explicitly requested.

package/AGENTS.md

@@ -14,18 +14,19 @@ 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
+## Product Docs Authoring
 
-### When To Edit `docs/`
+### When To Edit `product-docs/`
 
-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 `product-docs/` as a side effect of feature work, bug fixes,
+refactors, or other code changes. Product docs in this model are
+release-anchored:
 they describe the behavior of a specific release tag, not the partial state of
 a working branch.
 
-Touch `docs/` only when:
+Touch `product-docs/` only when:
 
-- A human explicitly asks you to refresh the docs for a release, typically
+- A human explicitly asks you to refresh product docs 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
   an existing project.
@@ -37,16 +38,16 @@ 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,
 document that exception in the area's README and in
-`docs/_authoring/areas/`.
+`product-docs/_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).
+live under [`product-docs/_authoring/`](product-docs/_authoring/). Start
+with [`product-docs/_authoring/README.md`](product-docs/_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 product docs, the per-area guides in
+[`product-docs/_authoring/areas/`](product-docs/_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

package/README.md

@@ -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. |
+| `product-docs/` | What the product does as of a known release or tag. | Only during explicit documentation 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.
+- `product-docs/` with a generic release-anchored documentation 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-product-docs
 npx code-anchored-context init --target ../existing-project
 ```
 
@@ -54,8 +54,8 @@ 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 `product-docs/_authoring/`.
+5. Create `product-docs/_authoring/areas/<area>.md` for each documented
    product or code area.
 6. Keep product or domain-specific documentation out of this template repo.
 
@@ -81,5 +81,5 @@ npx @your-scope/code-anchored-context init
 Working context can evolve with the branch. Product docs 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
+`release-doc-notes.md`; refresh `product-docs/` 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({ includeProductDocs: args.productDocs });
 }
 
 function parseArgs(argv) {
@@ -65,7 +65,7 @@ function parseArgs(argv) {
     release: defaultRelease,
     force: false,
     dryRun: false,
-    docs: true,
+    productDocs: true,
     help: false,
     version: false
   };
@@ -95,8 +95,8 @@ function parseArgs(argv) {
       continue;
     }
 
-    if (arg === '--no-docs') {
-      options.docs = false;
+    if (arg === '--no-product-docs' || arg === '--no-docs') {
+      options.productDocs = false;
       continue;
     }
 
@@ -170,7 +170,8 @@ 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-product-docs       Skip the product-docs/ starter files.
+  --no-docs               Alias for --no-product-docs.
   --force                 Replace existing generated directories.
   --dry-run               Show planned changes without writing files.
   -h, --help              Show help.
@@ -178,7 +179,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-product-docs
 `);
 }
 
@@ -215,7 +216,7 @@ class Installer {
     this.agentsFilePath = path.join(targetRoot, 'AGENTS.md');
   }
 
-  async init({ includeDocs }) {
+  async init({ includeProductDocs }) {
     await this.ensureDirectory(this.targetRoot);
 
     await this.installAgentsFile();
@@ -223,10 +224,10 @@ class Installer {
     await this.copyTemplatePath('context', 'context');
     await this.renameReleasePaths();
 
-    if (includeDocs) {
-      await this.copyTemplatePath('docs', 'docs');
+    if (includeProductDocs) {
+      await this.copyTemplatePath('product-docs', 'product-docs');
     } else {
-      this.note('skip docs/ (--no-docs)');
+      this.note('skip product-docs/ (--no-product-docs)');
     }
 
     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.
+`product-docs/` describes what has shipped for a release.
 
 ## Editing Rules
 
@@ -22,7 +22,7 @@ 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 `product-docs/`.
 - Use `release-doc-notes.md` inside an initiative to capture what may need to
   become product documentation later.
 - Create initiatives from `context/_templates/initiative/`.

package/context/README.md

@@ -6,14 +6,10 @@ 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.
+`product-docs/` for in-progress development planning.
 
 ## Start Here
 
-- `code-anchored-context.html` is a human-friendly visual brief for this
-  opinionated context practice.
-- `giving-ai-agents-context-around-code.md` is an article-form explanation of
-  Code-Anchored Context for human-agent collaboration.
 - `terminology.md` defines the shared vocabulary.
 - `current.md` points to the active release context.
 - `programs/` contains durable multi-release working context.
@@ -24,14 +20,14 @@ 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 product-docs/
 
-`context/` and `docs/` serve different jobs:
+`context/` and `product-docs/` 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. |
+| `product-docs/` | What the product does as of a release or tag. | Only during explicit documentation refresh work. |
 
 Working context can feed release documentation, but it is not product
 documentation. Capture that bridge in each initiative's
@@ -251,7 +247,7 @@ When changing behavior, agents should:
 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.
+   `product-docs/`, unless a human explicitly asks for documentation 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/...`
+- Product docs 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
+- Do not update `product-docs/` from this initiative unless a human
   explicitly asks for release documentation work.

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/`
+in progress. At release time, these notes help refresh `product-docs/`
 against the final shipped behavior.
 
-Do not edit `docs/` from normal development work unless a human
+Do not edit `product-docs/` from normal development work unless a human
 explicitly asks for a documentation refresh or a specific documentation fix.
 
 ## Product Behavior Changes
 
 - None yet.
 
-## Candidate Docs Areas
+## Candidate Product Docs Areas
 
-- `docs/<Area>/README.md`
-- `docs/<Area>/features/<feature>.md`
+- `product-docs/<Area>/README.md`
+- `product-docs/<Area>/features/<feature>.md`
 
 ## QA Or Support Notes
 
@@ -32,4 +32,3 @@ ship.
 - [ ] Update the relevant product documentation only after release-doc work
       is explicitly requested.
 - [ ] Add the release row if the documentation 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/...`
+- Product docs 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/release-doc-notes.md

@@ -4,17 +4,17 @@ Use this file to capture expected product-documentation 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
+Do not edit `product-docs/` from normal development work unless a human
 explicitly asks for a documentation refresh or a specific documentation fix.
 
 ## Expected Product Behavior Changes
 
 - None yet.
 
-## Candidate Docs Areas
+## Candidate Product Docs Areas
 
-- `docs/<Area>/README.md`
-- `docs/<Area>/features/<feature>.md`
+- `product-docs/<Area>/README.md`
+- `product-docs/<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. |
+| `product-docs/` | Released product documentation. It describes shipped 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 product documentation refresh work. This is the bridge to `product-docs/`. |
 | ADR | Architecture Decision Record. Use for durable decisions and tradeoffs. |
 | `brief.html` | Optional human-friendly presentation layer. |
 

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "code-anchored-context",
-  "version": "0.2.0",
-  "description": "Install repo-local agent context, release initiatives, and release-anchored docs scaffolding into an existing project.",
+  "version": "0.2.2",
+  "description": "Install repo-local agent context, release initiatives, and release-anchored product-docs scaffolding into an existing project.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "code-anchored-context": "./bin/code-anchored-context.js"
+    "code-anchored-context": "bin/code-anchored-context.js"
   },
   "files": [
     "AGENTS.md",
@@ -14,17 +14,13 @@
     "context/README.md",
     "context/_templates/",
     "context/backlog/",
-    "context/code-anchored-context-structure.md",
-    "context/code-anchored-context-why.md",
-    "context/code-anchored-context.html",
     "context/current.md",
-    "context/giving-ai-agents-context-around-code.md",
     "context/programs/",
     "context/releases/v0_1_0/README.md",
     "context/releases/v0_1_0/backlog.md",
     "context/releases/v0_1_0/initiatives/.gitkeep",
     "context/terminology.md",
-    "docs/",
+    "product-docs/",
     "bin/",
     "README.md",
     "LICENSE"
@@ -41,6 +37,6 @@
     "ai",
     "documentation",
     "working-context",
-    "docs"
+    "product-docs"
   ]
 }

package/product-docs/README.md

@@ -0,0 +1,61 @@
+# Product Docs
+
+This folder holds release-anchored product documentation for PROJECT_NAME.
+
+Product docs describe shipped behavior for a known release, tag, or explicit
+baseline. They are 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 documentation refreshes.
+- `_authoring/README.md` explains how humans and agents should author product
+  docs.
+- `_authoring/workflow.md` defines when product docs are refreshed and what
+  belongs here.
+- `_authoring/areas/` contains per-area authoring guidance.
+
+## Standard Layout
+
+```text
+product-docs/
+  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 `product-docs/_authoring/areas/`
+
+## Contributing
+
+- Refresh product docs only when explicitly asked.
+- For existing projects with little or no product documentation, create
+  baseline product docs 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 `product-docs/releases/index.md`.

package/{docs → product-docs}/_authoring/README.md

@@ -1,14 +1,14 @@
-# Docs Authoring Guide
+# Product Docs 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
+under `product-docs/`. Humans and agents both read from here to know how
 documentation 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 product docs are 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
+product-docs/_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 product docs root under `product-docs/`
 - feature pages that should exist
 - behavior that matters at release time
 - changes to ignore, such as pure refactors or test-only edits

package/{docs → product-docs}/_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
+product-docs/_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 product docs from a release diff
 without rediscovering the area's structure from scratch.
 
 ## Current Area Guides

package/{docs → product-docs}/_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>/`
+- Product docs root: `product-docs/<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 | Product docs page | Notes |
 | --- | --- | --- |
-| TBD | `docs/<Area>/features/<feature>.md` | TBD |
+| TBD | `product-docs/<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 `product-docs/_authoring/terminology.md`.
 
 ## Cross-Links
 
-List related areas and when docs should cross-link instead of duplicating
+List related areas and when product docs should cross-link instead of duplicating
 behavior.

package/{docs → product-docs}/_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
+Product docs 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.