code-anchored-context 0.1.0 → 0.1.1

package/AGENTS.md

@@ -27,6 +27,8 @@ Touch `Documentation/` only when:
 
 - A human explicitly asks you to refresh the 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.
 - 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
   broken link or factual inaccuracy.

package/Development/_templates/initiative/README.md

@@ -12,11 +12,15 @@ produce.
 
 ## Touched Areas
 
-- `src/<area>/...`
-- `deploy/...`
-- `automation/...`
-
-Remove entries that do not apply and add the real paths.
+- Product or runtime code: `path/to/...`
+- Interfaces, APIs, or contracts: `path/to/...`
+- Tests or verification: `path/to/...`
+- Delivery, CI/CD, build, or artifacts: `path/to/...`
+- Infrastructure, IaC, or environment config: `path/to/...`
+- Documentation 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.
 
 ## Current Source Of Truth
 

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

@@ -14,11 +14,15 @@ and what outcome it should produce.
 
 ## Touched Areas
 
-- `src/<area>/...`
-- `deploy/...`
-- `automation/...`
-
-Remove entries that do not apply and add the real paths.
+- Product or runtime code: `path/to/...`
+- Interfaces, APIs, or contracts: `path/to/...`
+- Tests or verification: `path/to/...`
+- Delivery, CI/CD, build, or artifacts: `path/to/...`
+- Infrastructure, IaC, or environment config: `path/to/...`
+- Documentation 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.
 
 ## Current Source Of Truth
 

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

@@ -6,9 +6,10 @@ 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
-`src/`, `deploy/`, 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.
+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.
 

package/Development/giving-ai-agents-context-around-code.md

@@ -74,8 +74,8 @@ flowchart LR
 ## The Navigation Problem
 
 In large repositories, agents and IDEs do not always open the workspace from
-the root. They may start in `src/`, `deploy/`, a specific application, or a
-nested project folder.
+the root. They may start in product code, CI/CD config, infrastructure code,
+generated artifacts, a specific application, or a nested project folder.
 
 If all guidance lives at the top, it may be missed. But if each area keeps its
 own plans, cross-project work becomes fragmented.
@@ -91,9 +91,9 @@ infrastructure context should live centrally under `Development/`.
 ```mermaid
 flowchart TD
   Root["Repository root"]
-  AreaA["src/AGENTS.md<br/>local signpost"]
-  AreaB["deploy/AGENTS.md<br/>local signpost"]
-  AreaC["apps/*/AGENTS.md<br/>local signpost"]
+  AreaA["product area AGENTS.md<br/>local signpost"]
+  AreaB["delivery area AGENTS.md<br/>local signpost"]
+  AreaC["nested project AGENTS.md<br/>local signpost"]
   Dev["Development/<br/>central working context"]
   Initiative["Release initiative<br/>single delivery story"]
 

package/Documentation/Welcome.md

@@ -35,8 +35,13 @@ Every documented area should have:
 ## 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.

package/Documentation/_authoring/README.md

@@ -23,7 +23,8 @@ Documentation/_authoring/areas/<area-slug>.md
 
 Each area guide should identify:
 
-- the code folder or folders that own the behavior
+- 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/`
 - feature pages that should exist
 - behavior that matters at release time

package/Documentation/_authoring/areas/_template.md

@@ -2,12 +2,20 @@
 
 ## Scope
 
-- Code root: `path/to/code`
+- 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>/`
 - Owner or reviewer: TBD
 
 Describe what this area owns and what it intentionally does not own.
 
+## Audience And Depth
+
+State any area-specific audience or depth rules. By default, write for
+Product Owners, QA, support, operators, customer engineers, and technical
+readers who need behavior, rules, data effects, permissions, errors, and
+operational expectations without private implementation detail.
+
 ## Feature Inventory
 
 | Feature | Documentation page | Notes |
@@ -41,6 +49,12 @@ Ignore changes that do not alter released behavior:
 List the files, folders, entry points, or search terms that help an agent map a
 release diff to documentation pages.
 
+## Baseline Discovery Notes
+
+Use this section when creating first-pass documentation for an existing
+project. List stable workflows, important entry points, source references,
+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`.

package/Documentation/_authoring/workflow.md

@@ -11,6 +11,9 @@ work. Humans or agents touch `Documentation/` 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
+  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.
@@ -24,15 +27,56 @@ 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
+
+There are two valid ways to introduce or maintain `Documentation/`.
+
+### Baseline Documentation
+
+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.
+
+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.
+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
+   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.
+
+Baseline docs are a snapshot of the system as adopted; they are not a promise
+that every undocumented behavior is unimportant.
+
+### Release-Forward Documentation
+
+Use this mode when the team chooses not to create a full baseline. In this
+mode, `Documentation/` 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.
+
+This is valid when a full baseline would be too expensive. The documentation
+becomes complete incrementally around behavior the team changes and releases.
+
 ## Cadence And Versioning
 
-Docs live under `Documentation/` and are refreshed once per release, at
-git-tag time, after release acceptance. Docs are anchored to the release tag;
-the docs at tag `release/v1_2_3` describe the behavior of that release.
+Docs live under `Documentation/`. 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.
 
 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.
+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`.
 
 ## Audience
 
@@ -47,6 +91,31 @@ Adjust this only when the project explicitly defines a different audience.
 - For readers who need more depth than the docs provide, link to the source
   rather than replicating the implementation in prose.
 
+## Writing Focus
+
+Write from behavior outward.
+
+Start with what a user, Product Owner, operator, API consumer, support person,
+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
+the accepted system does as of a release or baseline.
+
+Use progressive depth:
+
+1. Summary and purpose in product or domain language.
+2. Workflows, roles, permissions, and business rules.
+3. Inputs, outputs, data effects, integrations, errors, and edge cases.
+4. Operational expectations, configuration, and dependencies when relevant.
+5. Source references for verification, not as a substitute for explanation.
+
+Do not document private implementation structure unless it is needed to
+explain released behavior or support a reader's operational task.
+
 ## Two Levels Of Detail
 
 Every documented area has two layers:
@@ -105,11 +174,29 @@ 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/`.
-3. Update the area's `README.md` if the high-level picture changed.
-4. Update feature pages for behavior that changed.
-5. Ignore pure refactors, internal renames, test-only changes, formatting,
+3. Read relevant initiative `release-doc-notes.md` files under
+   `Development/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.
-6. Append one row to `Documentation/releases/index.md`.
+7. Append one row to `Documentation/releases/index.md`.
+
+## Source Order
+
+For release refreshes, start from release-owned context before falling back to
+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/`.
+4. Existing product documentation.
+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
+reference point named by the human. If no reference is named, use the current
+working tree and say so in the release index row.
 
 ## What Not To Document
 

package/Documentation/_templates/area/README.md

@@ -2,6 +2,15 @@
 
 Briefly describe what this area does, who uses it, and why it exists.
 
+## Reader Summary
+
+Explain the area in product or domain language. A Product Owner should be able
+to understand the purpose, scope, and user or business value from this section.
+
+## Primary Workflows
+
+- TBD
+
 ## Architecture At A Glance
 
 ```mermaid
@@ -15,6 +24,35 @@ flowchart LR
 
 - TBD
 
+## Data And State
+
+Describe the important records, files, queues, external state, or generated
+artifacts this area creates, reads, or changes.
+
+- TBD
+
+## Configuration And Dependencies
+
+List configuration, environment assumptions, external systems, scheduled jobs,
+or infrastructure this area depends on.
+
+- TBD
+
+## Operational Expectations
+
+Describe support, observability, recovery, audit, or routine operational
+expectations that matter to readers.
+
+- TBD
+
+## Source References
+
+Optional links to source files, generated references, dashboards, runbooks, or
+release context that help technical readers verify behavior. Keep explanation
+in this page instead of replacing it with links.
+
+- TBD
+
 ## Feature Pages
 
 - [Feature Name](features/feature-template.md)

package/Documentation/_templates/area/features/feature-template.md

@@ -1,25 +1,59 @@
 # Feature Name
 
-Describe the shipped behavior in domain language.
+Describe the shipped behavior in product or domain language. Start with what a
+Product Owner, QA reader, support person, operator, or API consumer can
+observe.
+
+## Reader Summary
+
+Explain what the feature does, why it matters, and the outcome it provides.
 
 ## Who Uses It
 
 - TBD
 
+## Entry Points
+
+Describe where the feature is triggered: UI, API, CLI, scheduled job,
+integration, import/export, or operator workflow.
+
+- TBD
+
 ## Behavior
 
 - TBD
 
+## Business Rules
+
+Describe rules, limits, lifecycle states, timing, or decision logic in
+reader-facing language.
+
+- TBD
+
 ## Inputs And Outputs
 
 | Input or output | Description |
 | --- | --- |
 | TBD | TBD |
 
+## Data And State Changes
+
+Describe important records, files, generated artifacts, messages, or external
+state this feature creates, reads, updates, deletes, or retains.
+
+- TBD
+
 ## Permissions And Validation
 
 - TBD
 
+## Configuration And Dependencies
+
+List flags, settings, environment requirements, external systems, or
+infrastructure dependencies that affect this feature.
+
+- TBD
+
 ## Errors And Edge Cases
 
 - TBD
@@ -27,3 +61,11 @@ Describe the shipped behavior in domain language.
 ## Operational Notes
 
 - TBD
+
+## Source References
+
+Optional links to source files, generated references, runbooks, dashboards, or
+release context that help technical readers verify behavior. Do not use this
+section for private implementation detail that has no reader-visible impact.
+
+- TBD

package/Documentation/releases/index.md

@@ -11,6 +11,8 @@ Docs at a given tag describe the behavior of that release.
 
 ## Notes For Future Release Rows
 
+- For an explicit baseline documentation pass, the tag may be a commit,
+  branch, date, or human-named baseline label when no release tag exists yet.
 - The first row may be a bootstrap refresh. Subsequent rows should describe
   incremental refreshes from `<previous-tag>..HEAD`.
 - "Areas refreshed" lists only areas with material behavior changes.

package/bin/code-anchored-context.js

@@ -212,6 +212,7 @@ class Installer {
     this.force = force;
     this.dryRun = dryRun;
     this.actions = [];
+    this.agentsFilePath = path.join(targetRoot, 'AGENTS.md');
   }
 
   async init({ includeDocumentation }) {
@@ -232,10 +233,13 @@ class Installer {
   }
 
   async installAgentsFile() {
-    const targetFile = path.join(this.targetRoot, 'AGENTS.md');
+    const targetFile = await this.findAgentsFile();
+    const targetDisplay = path.basename(targetFile);
+    this.agentsFilePath = targetFile;
 
     if (!await exists(targetFile)) {
       await this.copyTemplatePath('AGENTS.md', 'AGENTS.md');
+      this.agentsFilePath = path.join(this.targetRoot, 'AGENTS.md');
       return;
     }
 
@@ -249,16 +253,16 @@ class Installer {
       );
 
       if (updated === current) {
-        this.note('AGENTS.md already has Code-Anchored Context guidance');
+        this.note(`${targetDisplay} already has Code-Anchored Context guidance`);
         return;
       }
 
-      await this.writeFile(targetFile, updated, 'update AGENTS.md Code-Anchored Context section');
+      await this.writeFile(targetFile, updated, `update ${targetDisplay} Code-Anchored Context section`);
       return;
     }
 
     if (current.includes('.agents/skills/development-initiative-context/SKILL.md')) {
-      this.note('AGENTS.md already points to the development initiative skill');
+      this.note(`${targetDisplay} already points to the development initiative skill`);
       return;
     }
 
@@ -266,10 +270,33 @@ class Installer {
     await this.writeFile(
       targetFile,
       `${current}${separator}${section}\n`,
-      'append Code-Anchored Context guidance to AGENTS.md'
+      `append Code-Anchored Context guidance to ${targetDisplay}`
     );
   }
 
+  async findAgentsFile() {
+    const canonicalPath = path.join(this.targetRoot, 'AGENTS.md');
+
+    let entries;
+
+    try {
+      entries = await readdir(this.targetRoot, { withFileTypes: true });
+    } catch {
+      return canonicalPath;
+    }
+
+    if (entries.some((entry) => entry.isFile() && entry.name === 'AGENTS.md')) {
+      return canonicalPath;
+    }
+
+    const match = entries
+      .filter((entry) => entry.isFile() && entry.name.toLowerCase() === 'agents.md')
+      .map((entry) => entry.name)
+      .sort((left, right) => left.localeCompare(right))[0];
+
+    return match ? path.join(this.targetRoot, match) : canonicalPath;
+  }
+
   renderAgentSection() {
     return `${agentSectionStart}
 ## Code-Anchored Context
@@ -291,7 +318,13 @@ ${agentSectionEnd}`;
       `.agents/skills/${skillName}`
     );
 
-    const readmePath = path.join(this.targetRoot, '.agents/skills/README.md');
+    const readmeTarget = await this.findExistingTargetPath('.agents/skills/README.md');
+    const readmePath = readmeTarget.exists
+      ? readmeTarget.path
+      : path.join(this.targetRoot, '.agents/skills/README.md');
+    const readmeDisplay = readmeTarget.exists
+      ? readmeTarget.display
+      : '.agents/skills/README.md';
 
     if (!await exists(readmePath)) {
       await this.copyTemplatePath('.agents/skills/README.md', '.agents/skills/README.md');
@@ -301,7 +334,7 @@ ${agentSectionEnd}`;
     const current = await readFile(readmePath, 'utf8');
 
     if (current.includes(skillName)) {
-      this.note('.agents/skills/README.md already lists the development initiative skill');
+      this.note(`${readmeDisplay} already lists the development initiative skill`);
       return;
     }
 
@@ -316,26 +349,75 @@ ${agentSectionEnd}`;
     await this.writeFile(
       readmePath,
       `${current.trimEnd()}\n${entry}`,
-      'append development initiative skill to .agents/skills/README.md'
+      `append development initiative skill to ${readmeDisplay}`
     );
   }
 
   async copyTemplatePath(sourceRelative, targetRelative) {
     const sourcePath = path.join(packageRoot, sourceRelative);
+    const targetInfo = await this.findExistingTargetPath(targetRelative);
     const targetPath = path.join(this.targetRoot, targetRelative);
 
-    if (await exists(targetPath)) {
+    if (targetInfo.exists) {
+      const variantNote = targetInfo.caseVariant ? ` at ${targetInfo.display}` : '';
+
       if (!this.force) {
-        this.note(`skip ${targetRelative} (already exists; use --force to replace)`);
+        this.note(`skip ${targetRelative} (already exists${variantNote}; use --force to replace)`);
         return;
       }
 
-      await this.removePath(targetPath, `replace ${targetRelative}`);
+      await this.removePath(targetInfo.path, `replace ${targetInfo.display}`);
     }
 
     await this.copyRecursive(sourcePath, targetPath, targetRelative);
   }
 
+  async findExistingTargetPath(targetRelative) {
+    const parts = targetRelative.split('/').filter(Boolean);
+    let currentPath = this.targetRoot;
+    const displayParts = [];
+
+    for (const part of parts) {
+      let entries;
+
+      try {
+        entries = await readdir(currentPath, { withFileTypes: true });
+      } catch {
+        return this.missingTargetPath(targetRelative);
+      }
+
+      const exactMatch = entries.find((entry) => entry.name === part);
+      const caseMatch = exactMatch ?? entries.find(
+        (entry) => entry.name.toLowerCase() === part.toLowerCase()
+      );
+
+      if (!caseMatch) {
+        return this.missingTargetPath(targetRelative);
+      }
+
+      currentPath = path.join(currentPath, caseMatch.name);
+      displayParts.push(caseMatch.name);
+    }
+
+    const display = displayParts.join('/');
+
+    return {
+      caseVariant: display !== targetRelative,
+      display,
+      exists: true,
+      path: currentPath
+    };
+  }
+
+  missingTargetPath(targetRelative) {
+    return {
+      caseVariant: false,
+      display: targetRelative,
+      exists: false,
+      path: path.join(this.targetRoot, targetRelative)
+    };
+  }
+
   async copyRecursive(sourcePath, targetPath, displayPath) {
     if (this.shouldSkipTemplatePath(displayPath)) {
       this.note(`skip ${displayPath} (template repository context)`);
@@ -533,7 +615,7 @@ No initiatives registered yet.
     console.log(`${prefix}Code-Anchored Context ready for ${this.projectName}.`);
 
     if (!this.dryRun) {
-      console.log(`Next: ask your agent to read ${path.join(this.targetRoot, 'AGENTS.md')}.`);
+      console.log(`Next: ask your agent to read ${this.agentsFilePath}.`);
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-anchored-context",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Install repo-local agent context, development initiatives, and release-anchored documentation scaffolding into an existing project.",
   "license": "MIT",
   "type": "module",