code-anchored-context 0.1.1 → 0.2.1

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

@@ -1,7 +1,7 @@
-# Documentation Authoring Guide
+# Docs Authoring Guide
 
 This subtree owns all guidance for authoring and refreshing the documentation
-under `Documentation/`. Humans and agents both read from here to know how
+under `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.
 
@@ -18,14 +18,14 @@ and which domain terminology to use.
 Create one authoring guide per documented area:
 
 ```text
-Documentation/_authoring/areas/<area-slug>.md
+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 documentation root under `Documentation/`
+- the docs root under `docs/`
 - feature pages that should exist
 - behavior that matters at release time
 - changes to ignore, such as pure refactors or test-only edits

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

@@ -5,7 +5,7 @@ This folder contains one authoring guide per documented area.
 Create a guide from `_template.md` when adding a documentation area:
 
 ```text
-Documentation/_authoring/areas/<area-slug>.md
+docs/_authoring/areas/<area-slug>.md
 ```
 
 Each guide should help a human or agent refresh docs from a release diff

package/{Documentation → 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`
-- Documentation root: `Documentation/<Area>/`
+- Docs root: `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 | Documentation page | Notes |
+| Feature | Docs page | Notes |
 | --- | --- | --- |
-| TBD | `Documentation/<Area>/features/<feature>.md` | TBD |
+| TBD | `docs/<Area>/features/<feature>.md` | TBD |
 
 ## What Matters At Release Time
 
@@ -57,7 +57,7 @@ known gaps, and questions that should not yet appear in product-facing docs.
 
 ## Terminology
 
-List area-specific terms or link to `Documentation/_authoring/terminology.md`.
+List area-specific terms or link to `docs/_authoring/terminology.md`.
 
 ## Cross-Links
 

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

@@ -2,7 +2,7 @@
 
 Use this file to define the domain language that documentation should use.
 
-Documentation should translate code-level names into reader-facing domain
+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.
 

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

@@ -1,4 +1,4 @@
-# Documentation Workflow
+# Docs Workflow
 
 This file defines how documentation is versioned, refreshed, and structured
 across the repo. It applies to all documented areas; area-specific guidance
@@ -7,7 +7,7 @@ lives in [`areas/`](areas/).
 ## When Docs Get Edited
 
 Doc refresh is an explicit, on-request activity, not a side effect of code
-work. Humans or agents touch `Documentation/` only when:
+work. Humans or agents touch `docs/` only when:
 
 - A human explicitly asks for a release-time refresh, typically after the
   release tag is cut and QA has signed off.
@@ -27,11 +27,11 @@ 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.
 
-## Documentation Modes
+## Docs Modes
 
-There are two valid ways to introduce or maintain `Documentation/`.
+There are two valid ways to introduce or maintain `docs/`.
 
-### Baseline Documentation
+### Baseline Docs
 
 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
@@ -42,23 +42,23 @@ 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
-   `Documentation/_authoring/areas/` before writing product-facing pages.
+   `docs/_authoring/areas/` before writing product-facing 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 `Documentation/releases/index.md`. If
+5. Record the baseline reference in `docs/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 `Documentation/`. Capture open
-   questions in `Development/` or in the area authoring guide.
+6. Leave uncertain or future behavior out of `docs/`. 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.
 
-### Release-Forward Documentation
+### Release-Forward Docs
 
 Use this mode when the team chooses not to create a full baseline. In this
-mode, `Documentation/` may start sparse. Agents capture documentation impact
+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.
 
@@ -67,7 +67,7 @@ becomes complete incrementally around behavior the team changes and releases.
 
 ## Cadence And Versioning
 
-Docs live under `Documentation/`. After any explicit baseline pass, they are
+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.
@@ -76,7 +76,7 @@ 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
-`Documentation/releases/index.md`.
+`docs/releases/index.md`.
 
 ## Audience
 
@@ -100,9 +100,9 @@ or business process can observe. Add technical detail only when it affects
 released behavior, configuration, permissions, data, integrations, errors,
 support, operations, or auditability.
 
-Documentation 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 `Documentation/` describes what
+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.
 
 Use progressive depth:
@@ -127,7 +127,7 @@ Every documented area has two layers:
 Standard per-area layout:
 
 ```text
-Documentation/<Area>/
+docs/<Area>/
   README.md
   features/
     <feature>.md
@@ -173,14 +173,14 @@ When invoked to refresh docs 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 `Documentation/_authoring/areas/`.
+2. Read the matching area guide in `docs/_authoring/areas/`.
 3. Read relevant initiative `release-doc-notes.md` files under
-   `Development/releases/<release>/initiatives/`.
+   `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 `Documentation/releases/index.md`.
+7. Append one row to `docs/releases/index.md`.
 
 ## Source Order
 
@@ -189,7 +189,7 @@ source inspection:
 
 1. Previous release tag to current release diff.
 2. Relevant initiative `release-doc-notes.md` files.
-3. Matching area guide under `Documentation/_authoring/areas/`.
+3. Matching area guide under `docs/_authoring/areas/`.
 4. Existing product documentation.
 5. Source code, tests, config, CI/CD, infrastructure, and generated artifacts
    only as needed to verify shipped behavior.
@@ -207,4 +207,4 @@ working tree and say so in the release index row.
 - Transient migration scaffolding that will be removed before or soon after
   the release.
 - Draft plans, undecided architecture, or open implementation questions. Those
-  belong in `Development/`.
+  belong in `context/`.

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

@@ -1,4 +1,4 @@
-# Release Documentation Index
+# Release Docs Index
 
 One row per tagged release. Tag names default to `release/vMAJOR_MINOR_PATCH`
 unless the project documents a different convention.

package/package.json

@@ -1,30 +1,26 @@
 {
   "name": "code-anchored-context",
-  "version": "0.1.1",
-  "description": "Install repo-local agent context, development initiatives, and release-anchored documentation scaffolding into an existing project.",
+  "version": "0.2.1",
+  "description": "Install repo-local agent context, release initiatives, and release-anchored 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",
     ".agents/",
-    "Development/AGENTS.md",
-    "Development/README.md",
-    "Development/_templates/",
-    "Development/backlog/",
-    "Development/code-anchored-context-structure.md",
-    "Development/code-anchored-context-why.md",
-    "Development/code-anchored-context.html",
-    "Development/current.md",
-    "Development/giving-ai-agents-context-around-code.md",
-    "Development/programs/",
-    "Development/releases/v0_1_0/README.md",
-    "Development/releases/v0_1_0/backlog.md",
-    "Development/releases/v0_1_0/initiatives/.gitkeep",
-    "Development/terminology.md",
-    "Documentation/",
+    "context/AGENTS.md",
+    "context/README.md",
+    "context/_templates/",
+    "context/backlog/",
+    "context/current.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/",
     "bin/",
     "README.md",
     "LICENSE"
@@ -40,6 +36,7 @@
     "codex",
     "ai",
     "documentation",
-    "development-context"
+    "working-context",
+    "docs"
   ]
 }

package/Development/code-anchored-context-structure.md

@@ -1,133 +0,0 @@
-# Code-Anchored Context: The Structure
-
-This is the companion to the
-[reasoning article](code-anchored-context-why.md). It covers how development
-context is laid out so both humans and agents can navigate it.
-
-## Denormalize Navigation, Not Knowledge
-
-Agents and IDEs do not always open from the repo root. They may start in
-product code, CI/CD config, infrastructure code, generated artifacts, or a
-nested app. If all guidance lives at the top, it gets missed. If each area
-keeps its own plans, cross-project work fragments.
-
-> Denormalize navigation, not knowledge.
-
-Local `AGENTS.md` files point agents toward the right place. But plans, specs,
-ADRs, release context, testing strategy, delivery notes, and infrastructure
-context live centrally under `Development/`.
-
-## The Core Model
-
-Vocabulary is captured in `Development/terminology.md`. The main containers:
-
-```text
-Program                  Long-lived multi-release effort.
-Planned initiative       A scoped future slice inside a program.
-Release initiative       Active or historical work for a specific release.
-Development backlog item Isolated work cut from scope but worth preserving.
-Program release slice    What a release contributes to a program.
-```
-
-Each kind of context gets a home:
-
-```text
-Development/
-  terminology.md
-  current.md
-  programs/
-  backlog/
-  releases/
-  _templates/
-```
-
-Structure follows delivery concerns, not technologies. Name a file for the
-knowledge it preserves, not the tool that produced it.
-
-## Release Initiatives
-
-The main unit of active delivery:
-
-```text
-Development/releases/<version>/initiatives/<initiative>/
-  README.md   plan.md   spec.md   interface.md   architecture.md
-  testing.md  delivery.md  infrastructure.md  operations.md
-  backlog.md  decisions/  release-doc-notes.md
-```
-
-The most important file is `plan.md` — the working alignment space. It can be
-messy with notes, options, and tradeoffs, with one rule:
-
-> `plan.md` may be messy, but it must not be the only place settled truth lives.
-
-Once something stabilizes, it moves to a durable file:
-
-```text
-spec.md              What the system should do.
-interface.md         How clients, APIs, config, or tools interact with it.
-architecture.md      Internal shape, boundaries, data flow, tradeoffs.
-testing.md           Verification strategy, coverage, gates, known gaps.
-delivery.md          CI/CD, build, deployment, promotion, release toggles.
-infrastructure.md    Environments, IaC, networking, identity, storage, secrets.
-operations.md        Runtime/support: observability, failure modes, rollback.
-backlog.md           Trackable work items and progress.
-decisions/           Durable decisions and consequences (ADRs).
-release-doc-notes.md What should become product documentation later.
-```
-
-Not every initiative needs every file. The point is to give stable knowledge a
-place to land — testing, delivery, and infrastructure are first-class context,
-not afterthoughts buried in pipeline files or PRs.
-
-## Programs And Planned Initiatives
-
-Some work is bigger than one release. A program holds durable multi-release
-context:
-
-```text
-Development/programs/<program>/
-  README.md  context.md  roadmap.md  backlog.md
-  decisions/  planned-initiatives/  releases/
-```
-
-Future work that is clear enough to plan — but whose target release is not
-current yet — becomes a planned initiative:
-
-```text
-Development/programs/<program>/planned-initiatives/<initiative>/
-```
-
-When the target release becomes current, it is promoted into
-`Development/releases/<version>/initiatives/<initiative>/`. Promotion is
-explicit; the original planned initiative stays as historical context.
-
-## Development Backlog
-
-Work cut from scope but worth preserving — when it doesn't justify a program or
-planned initiative — lives in:
-
-```text
-Development/backlog/items/<originating-initiative>--<item>.md
-```
-
-Each item records where it came from, why it was deferred, future value, and
-re-entry criteria. If picked up later, it is marked promoted and linked — never
-silently rewritten.
-
-## Release Transitions
-
-Changing the current release is more than editing a pointer. When
-`Development/current.md` moves to a new release, agents should scan program
-planned initiatives, promote items targeting the new release into the release
-folder, update links both ways, and preserve the originals as history.
-
-```mermaid
-flowchart TD
-  Start["Set a new current release"]
-  Scan["Scan program planned initiatives"]
-  Promote["Promote into releases/<version>/initiatives/"]
-  Link["Update links both ways"]
-  Preserve["Preserve original as history"]
-
-  Start --> Scan --> Promote --> Link --> Preserve
-```

package/Development/code-anchored-context-why.md

@@ -1,80 +0,0 @@
-# Code-Anchored Context: Giving AI Agents The Context Around The Code
-
-AI agents are good at reading repositories, editing files, and following
-instructions. But in large codebases, code is not the whole story.
-
-The hard part is not whether an agent can change a file. It is whether it
-understands the intent behind the change, the current release scope, the
-decisions already made, the work deliberately deferred, how the change should
-be verified, how it ships, and what infrastructure or operational risks
-surround it.
-
-That context usually exists — in chats, tickets, pull request comments,
-planning notes, and people's heads — but agents need it in a structured,
-discoverable form.
-
-## Documentation vs Development
-
-This is why I separate **released product documentation** from **development
-context**:
-
-```text
-Documentation/   What shipped.
-Development/      What we are planning, building, deciding, testing,
-                  shipping, hosting, deferring, and learning.
-```
-
-Product documentation stays stable and release-accurate: it describes a known
-release, not an unfinished branch. Development context is allowed to evolve —
-it is where humans and agents work through ambiguity.
-
-## The Principle
-
-I think of this as **Code-Anchored Context**. Not a methodology — a rule of
-thumb:
-
-> Keep truth as close to code as possible, and keep the surrounding context
-> structured enough that both humans and agents can find it.
-
-It is opinionated on purpose: prefer repository-local context, explicit
-lifetimes, and navigable structure over scattered notes that only make sense
-to the people who were in the room. Repository-local context scales beyond one
-person.
-
-## Why It Travels
-
-When context is materialized in the repository, it stops being tied to one
-chat transcript, IDE, agent, or session. A team can switch tools without
-losing the trail of why the system is shaped the way it is. The next human or
-agent opens the repo and continues from the same accumulated understanding
-instead of reconstructing it from memory.
-
-```mermaid
-flowchart LR
-  Code["Codebase<br/>What exists"]
-  Dev["Development/<br/>What is being planned, built, decided, tested, shipped, deferred"]
-  Docs["Documentation/<br/>What shipped in a known release"]
-  Agents["Agents and humans"]
-
-  Agents --> Code
-  Agents --> Dev
-  Dev -->|"release-doc-notes.md captures future docs impact"| Docs
-  Docs -->|"stable release truth"| Agents
-```
-
-## Why It Matters
-
-Code-Anchored Context is context continuity. It helps agents and humans answer:
-
-- What is active now, and what belongs to a future phase?
-- What was cut from scope, and why was a decision made?
-- How should this be tested, and what gates must pass before release?
-- How will it ship, and what infrastructure does it depend on?
-- What should become product documentation later?
-- What reasoning needs to survive a change of IDE, agent, or session?
-
-Code tells an agent *what exists*. Development context tells it *why* it
-exists, where it is going, what has been decided, and what was left for later.
-
-For the concrete folder layout, see the companion article,
-[Code-Anchored Context: The Structure](code-anchored-context-structure.md).