reference-docs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo Mendez Rodriguez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# reference-docs
+
+Invocation-only skills and scaffold for release-anchored reference documentation.
+
+Install into a project:
+
+```bash
+npx reference-docs init --project-name "My App"
+```
+
+Adds `reference/` and skills `reference-from-tags` and `reference-baseline`.
+
+Works independently of any planning workflow — the tag diff is the source of truth.
+
+## Use
+
+```text
+Create a baseline reference for this repo.
+Refresh reference from <previous-tag> to <new-tag>.
+```
+
+Skills are invocation-only — they do not run automatically.
+
+Options: `--target`, `--dry-run`, `--force`, `status`.

package/bin/reference-docs.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runCli, reportError } from '../lib/installer.js';
+
+const cliName = 'reference-docs';
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const packageJson = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+
+const agentsStart = '<!-- reference-docs:start -->';
+const agentsEnd = '<!-- reference-docs:end -->';
+
+const skills = [
+  {
+    name: 'reference-from-tags',
+    readmeEntry:
+      '- `reference-from-tags` - invoke explicitly to refresh `reference/` from the diff between two release tags.'
+  },
+  {
+    name: 'reference-baseline',
+    readmeEntry:
+      '- `reference-baseline` - invoke explicitly for a first baseline pass under `reference/`.'
+  }
+];
+
+function renderAgentSection(projectName) {
+  return `${agentsStart}
+## Reference Docs
+
+Release-anchored reference under [\`reference/\`](reference/). Describes accepted behavior as of a release tag or baseline — not edited as a side effect of feature work.
+
+Authoring workflow: [\`reference/_authoring/\`](reference/_authoring/README.md).
+
+Invocation-only skills — ask by name:
+
+- [\`.agents/skills/reference-from-tags/SKILL.md\`](.agents/skills/reference-from-tags/SKILL.md) — refresh from a tag-to-tag diff.
+- [\`.agents/skills/reference-baseline/SKILL.md\`](.agents/skills/reference-baseline/SKILL.md) — document current accepted behavior.
+${agentsEnd}`;
+}
+
+const config = {
+  cliName,
+  packageRoot,
+  packageJson,
+  summaryLabel: 'Reference Docs',
+  metadataPath: '.reference-docs/install.json',
+  skills,
+  agents: {
+    start: agentsStart,
+    end: agentsEnd,
+    render: renderAgentSection
+  },
+  nextSteps: [
+    'Then: invoke .agents/skills/reference-baseline/SKILL.md for a first baseline, or reference-from-tags at release time.'
+  ]
+};
+
+runCli(config, process.argv.slice(2)).catch((error) => reportError(error, cliName));

package/lib/installer.js

@@ -0,0 +1,553 @@
+import { execPath } from 'node:process';
+import { constants as fsConstants } from 'node:fs';
+import { access, mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const agentsSkillsRelative = '.agents/skills';
+
+/**
+ * Generic installer shared by durable-context and reference-docs packages.
+ *
+ * Each package supplies a `config` describing its payload:
+ *   - cliName:        bin name, used in help and error text
+ *   - packageRoot:    absolute path to the package directory
+ *   - packageJson:    parsed package.json of the package
+ *   - skills:         [{ name, readmeEntry }] copied into .agents/skills
+ *   - agents:         { start, end, render(projectName) } AGENTS.md section
+ *   - metadataPath:   relative path of the install metadata file in the target
+ *   - nextSteps:      strings printed after a successful install
+ *   - summaryLabel:   short label used in the final summary line
+ */
+export async function runCli(config, argv) {
+  const args = parseArgs(argv, config);
+
+  if (args.help) {
+    printHelp(config);
+    return;
+  }
+
+  if (args.version) {
+    console.log(config.packageJson.version);
+    return;
+  }
+
+  if (args.command === 'status') {
+    await printStatus(config, args.target);
+    return;
+  }
+
+  if (args.command !== 'init') {
+    throw new Error(`Unknown command "${args.command}". Run "${config.cliName} --help".`);
+  }
+
+  const targetRoot = path.resolve(args.target);
+  const projectName = args.projectName ?? (await inferProjectName(targetRoot));
+  const installer = new Installer({
+    config,
+    targetRoot,
+    projectName,
+    force: args.force,
+    dryRun: args.dryRun
+  });
+
+  await installer.init();
+}
+
+function parseArgs(argv, config) {
+  const options = {
+    command: 'help',
+    target: process.cwd(),
+    projectName: undefined,
+    force: false,
+    dryRun: false,
+    help: false,
+    version: false
+  };
+
+  const positionals = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === '--version' || arg === '-v') {
+      options.version = true;
+      continue;
+    }
+
+    if (arg === '--force') {
+      options.force = true;
+      continue;
+    }
+
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+      continue;
+    }
+
+    if (arg.startsWith('--target=')) {
+      options.target = arg.slice('--target='.length);
+      continue;
+    }
+
+    if (arg === '--target') {
+      options.target = readOptionValue(argv, index, '--target');
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--project-name=')) {
+      options.projectName = arg.slice('--project-name='.length);
+      continue;
+    }
+
+    if (arg === '--project-name') {
+      options.projectName = readOptionValue(argv, index, '--project-name');
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown option "${arg}". Run "${config.cliName} --help".`);
+    }
+
+    positionals.push(arg);
+  }
+
+  if (positionals.length > 1) {
+    throw new Error(`Unexpected arguments: ${positionals.slice(1).join(' ')}`);
+  }
+
+  options.command = positionals[0] ?? (options.help || options.version ? 'meta' : 'help');
+  options.help = options.help || options.command === 'help';
+
+  return options;
+}
+
+function readOptionValue(argv, index, optionName) {
+  const value = argv[index + 1];
+
+  if (!value || value.startsWith('-')) {
+    throw new Error(`${optionName} requires a value.`);
+  }
+
+  return value;
+}
+
+function printHelp(config) {
+  console.log(`${config.cliName}
+
+Usage:
+  ${config.cliName} init [options]
+  ${config.cliName} status [options]
+
+Options:
+  --target <path>          Project root to install into. Defaults to cwd.
+  --project-name <name>    Name used to replace PROJECT_NAME placeholders.
+  --force                  Replace existing generated directories.
+  --dry-run                Show planned changes without writing files.
+  -h, --help               Show help.
+  -v, --version            Show package version.
+
+Examples:
+  npx ${config.packageJson.name} init --project-name "My App"
+  npx ${config.packageJson.name}@${config.packageJson.version} init --project-name "My App"
+  npx ${config.packageJson.name} status --target ../existing-project
+
+The status command reads ${config.metadataPath} from an initialized project.
+`);
+}
+
+async function inferProjectName(targetRoot) {
+  try {
+    const packageJson = JSON.parse(await readFile(path.join(targetRoot, 'package.json'), 'utf8'));
+
+    if (typeof packageJson.name === 'string' && packageJson.name.trim()) {
+      return packageJson.name.replace(/^@[^/]+\//, '');
+    }
+  } catch {
+    // Fall through to the directory name.
+  }
+
+  return path.basename(targetRoot);
+}
+
+class Installer {
+  constructor({ config, targetRoot, projectName, force, dryRun }) {
+    this.config = config;
+    this.templateDir = path.join(config.packageRoot, 'template');
+    this.targetRoot = targetRoot;
+    this.projectName = projectName;
+    this.force = force;
+    this.dryRun = dryRun;
+    this.actions = [];
+    this.agentsFilePath = path.join(targetRoot, 'AGENTS.md');
+  }
+
+  async init() {
+    await this.ensureDirectory(this.targetRoot);
+
+    await this.installAgentsFile();
+    await this.installSkills();
+    await this.installPayloadRoots();
+    await this.writeMetadata();
+
+    this.printSummary();
+  }
+
+  async installPayloadRoots() {
+    const entries = await readdir(this.templateDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.name === 'AGENTS.md' || entry.name === '.agents' || entry.name === '.DS_Store') {
+        continue;
+      }
+
+      await this.copyTemplatePath(entry.name, entry.name);
+    }
+  }
+
+  async installAgentsFile() {
+    const targetFile = await this.findAgentsFile();
+    const targetDisplay = path.basename(targetFile);
+    this.agentsFilePath = targetFile;
+
+    const section = this.config.agents.render(this.projectName);
+    const { start, end } = this.config.agents;
+
+    if (!(await exists(targetFile))) {
+      const templateAgents = path.join(this.templateDir, 'AGENTS.md');
+
+      if (await exists(templateAgents)) {
+        const text = (await readFile(templateAgents, 'utf8')).replaceAll('PROJECT_NAME', this.projectName);
+        await this.writeFile(path.join(this.targetRoot, 'AGENTS.md'), text, 'create AGENTS.md');
+        this.agentsFilePath = path.join(this.targetRoot, 'AGENTS.md');
+        return;
+      }
+
+      await this.writeFile(path.join(this.targetRoot, 'AGENTS.md'), `${section}\n`, 'create AGENTS.md');
+      this.agentsFilePath = path.join(this.targetRoot, 'AGENTS.md');
+      return;
+    }
+
+    const current = await readFile(targetFile, 'utf8');
+
+    if (current.includes(start) && current.includes(end)) {
+      const updated = current.replace(
+        new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}`),
+        section
+      );
+
+      if (updated === current) {
+        this.note(`${targetDisplay} already has the ${this.config.summaryLabel} guidance`);
+        return;
+      }
+
+      await this.writeFile(targetFile, updated, `update ${targetDisplay} ${this.config.summaryLabel} section`);
+      return;
+    }
+
+    const separator = current.endsWith('\n') ? '\n' : '\n\n';
+    await this.writeFile(
+      targetFile,
+      `${current}${separator}${section}\n`,
+      `append ${this.config.summaryLabel} 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;
+  }
+
+  async installSkills() {
+    for (const skill of this.config.skills) {
+      await this.copyTemplatePath(
+        `${agentsSkillsRelative}/${skill.name}`,
+        `${agentsSkillsRelative}/${skill.name}`
+      );
+    }
+
+    const readmeTarget = await this.findExistingTargetPath(`${agentsSkillsRelative}/README.md`);
+    const readmePath = readmeTarget.exists
+      ? readmeTarget.path
+      : path.join(this.targetRoot, `${agentsSkillsRelative}/README.md`);
+    const readmeDisplay = readmeTarget.exists ? readmeTarget.display : `${agentsSkillsRelative}/README.md`;
+
+    if (!(await exists(readmePath))) {
+      await this.copyTemplatePath(`${agentsSkillsRelative}/README.md`, `${agentsSkillsRelative}/README.md`);
+      return;
+    }
+
+    const current = await readFile(readmePath, 'utf8');
+    const missingSkills = this.config.skills.filter((skill) => !current.includes(skill.name));
+
+    if (missingSkills.length === 0) {
+      this.note(`${readmeDisplay} already lists the ${this.config.summaryLabel} skills`);
+      return;
+    }
+
+    const entry = [
+      '',
+      `## ${this.config.summaryLabel} Skills`,
+      '',
+      ...missingSkills.map((skill) => skill.readmeEntry),
+      ''
+    ].join('\n');
+
+    await this.writeFile(
+      readmePath,
+      `${current.trimEnd()}\n${entry}`,
+      `append ${this.config.summaryLabel} skills to ${readmeDisplay}`
+    );
+  }
+
+  async copyTemplatePath(sourceRelative, targetRelative) {
+    const sourcePath = path.join(this.templateDir, sourceRelative);
+    const targetInfo = await this.findExistingTargetPath(targetRelative);
+
+    if (!(await exists(sourcePath))) {
+      return false;
+    }
+
+    const targetPath = path.join(this.targetRoot, targetRelative);
+
+    if (targetInfo.exists) {
+      const variantNote = targetInfo.caseVariant ? ` at ${targetInfo.display}` : '';
+
+      if (!this.force) {
+        this.note(`skip ${targetRelative} (already exists${variantNote}; use --force to replace)`);
+        return false;
+      }
+
+      await this.removePath(targetInfo.path, `replace ${targetInfo.display}`);
+    }
+
+    await this.copyRecursive(sourcePath, targetPath, targetRelative);
+    return true;
+  }
+
+  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) {
+    const sourceStats = await stat(sourcePath);
+
+    if (sourceStats.isDirectory()) {
+      await this.ensureDirectory(targetPath, `create ${displayPath}/`);
+      const entries = await readdir(sourcePath, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (entry.name === '.DS_Store') {
+          continue;
+        }
+
+        await this.copyRecursive(
+          path.join(sourcePath, entry.name),
+          path.join(targetPath, entry.name),
+          path.posix.join(displayPath, entry.name)
+        );
+      }
+
+      return;
+    }
+
+    const contents = await readFile(sourcePath);
+    const transformed = this.transformText(contents);
+    await this.writeFile(targetPath, transformed, `create ${displayPath}`);
+  }
+
+  transformText(contents) {
+    return contents.toString('utf8').replaceAll('PROJECT_NAME', this.projectName);
+  }
+
+  async writeMetadata() {
+    const metadataPath = path.join(this.targetRoot, this.config.metadataPath);
+    const previous = await readOptionalJson(metadataPath);
+    const now = new Date().toISOString();
+    const metadata = {
+      schemaVersion: 1,
+      packageName: this.config.packageJson.name,
+      installedVersion: this.config.packageJson.version,
+      firstInstalledVersion:
+        previous?.firstInstalledVersion ?? previous?.installedVersion ?? this.config.packageJson.version,
+      firstInstalledAt: previous?.firstInstalledAt ?? previous?.installedAt ?? now,
+      lastUpdatedAt: now,
+      projectName: this.projectName,
+      installedSkills: this.config.skills.map((skill) => skill.name)
+    };
+
+    await this.writeFile(
+      metadataPath,
+      `${JSON.stringify(metadata, null, 2)}\n`,
+      `${previous ? 'update' : 'create'} ${this.config.metadataPath}`
+    );
+  }
+
+  async ensureDirectory(directory, message) {
+    if (message) {
+      this.note(message);
+    }
+
+    if (!this.dryRun) {
+      await mkdir(directory, { recursive: true });
+    }
+  }
+
+  async removePath(filePath, message) {
+    this.note(message);
+
+    if (!this.dryRun) {
+      await rm(filePath, { recursive: true, force: true });
+    }
+  }
+
+  async writeFile(filePath, contents, message) {
+    this.note(message);
+
+    if (!this.dryRun) {
+      await mkdir(path.dirname(filePath), { recursive: true });
+      await writeFile(filePath, contents);
+    }
+  }
+
+  note(message) {
+    this.actions.push(message);
+  }
+
+  printSummary() {
+    const prefix = this.dryRun ? '[dry-run] ' : '';
+
+    for (const action of this.actions) {
+      console.log(`${prefix}${action}`);
+    }
+
+    console.log(`${prefix}${this.config.summaryLabel} ready for ${this.projectName}.`);
+
+    if (!this.dryRun) {
+      console.log(`Next: ask your agent to read ${this.agentsFilePath}.`);
+
+      for (const step of this.config.nextSteps ?? []) {
+        console.log(step);
+      }
+    }
+  }
+}
+
+async function printStatus(config, target) {
+  const targetRoot = path.resolve(target);
+  const metadataPath = path.join(targetRoot, config.metadataPath);
+  const metadata = await readOptionalJson(metadataPath);
+
+  console.log(`${config.summaryLabel} status for ${targetRoot}`);
+  console.log(`Running CLI version: ${config.packageJson.version}`);
+
+  if (!metadata) {
+    console.log('Installed metadata: not found');
+    console.log(`Metadata path: ${config.metadataPath}`);
+    return;
+  }
+
+  console.log(`Installed version: ${metadata.installedVersion ?? 'Unknown'}`);
+  console.log(`Project: ${metadata.projectName ?? 'Unknown'}`);
+  console.log(`Installed skills: ${formatList(metadata.installedSkills)}`);
+  console.log(`Metadata path: ${config.metadataPath}`);
+
+  if (metadata.installedVersion && metadata.installedVersion !== config.packageJson.version) {
+    console.log('Note: running CLI version differs from installed metadata.');
+  }
+}
+
+function formatList(value) {
+  return Array.isArray(value) && value.length > 0 ? value.join(', ') : 'Unknown';
+}
+
+async function readOptionalJson(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+async function exists(filePath) {
+  try {
+    await access(filePath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function reportError(error, cliName) {
+  console.error(error.message);
+  console.error(`Run "${path.basename(execPath)} ${cliName} --help" for usage.`);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "reference-docs",
+  "version": "1.0.0",
+  "description": "Invocation-only skills and scaffold for release-anchored reference documentation refreshed from tag diffs.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "reference-docs": "bin/reference-docs.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "template/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "agents",
+    "ai",
+    "documentation",
+    "reference",
+    "release-notes"
+  ]
+}

package/template/.agents/skills/README.md

@@ -0,0 +1,6 @@
+# Project Skills
+
+Invocation-only — ask by name.
+
+- `reference-from-tags` — refresh `reference/` from a tag-to-tag diff.
+- `reference-baseline` — first baseline pass under `reference/`.

package/template/.agents/skills/reference-baseline/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: reference-baseline
+description: Document current accepted behavior under reference/ as a first baseline. Use ONLY when the human explicitly asks for baseline/initial reference or domain terminology. Do not trigger automatically.
+---
+
+# Reference Baseline
+
+Documentation only — no executable changes.
+
+## Invariants
+
+- Read `AGENTS.md`, `reference/README.md`, `reference/_authoring/README.md`, and `reference/_authoring/workflow.md` first.
+- Accepted current behavior → `reference/`. Uncertain/disputed → `reference/_authoring/baseline-clarifications.md`.
+- Source-backed facts only; extend existing docs rather than replacing wholesale.
+- Optional: read `context/project-profile.md` when durable-context is installed.
+
+## Workflow
+
+1. **Scope** — whole repo, one area, or as named by human. Record reference point in `reference/releases/index.md`.
+2. **Inspect** — manifests, source roots, tests, CI/CD, IaC, observability, existing docs (use `rg` and repo tooling).
+3. **Area guides** — create/update `reference/_authoring/areas/<slug>.md` from `_template.md`.
+4. **Terminology** — update `reference/_authoring/terminology.md`; ambiguities → `baseline-clarifications.md`.
+5. **Pages** — create/update `reference/<Area>/README.md` and `features/*.md` using `_templates/area/`.
+6. **Record** — row in `reference/releases/index.md` (tag or `baseline/<label>`).
+7. **Validate** — documentation-only diff; summarize areas, pages, open clarifications.
+
+Procedural detail: `reference/_authoring/workflow.md` (baseline mode, audience, layout).

package/template/.agents/skills/reference-from-tags/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: reference-from-tags
+description: Refresh reference/ from the diff between two release tags. Use ONLY when the human explicitly asks to refresh reference for a release, update from tags, update a page, or fix a demonstrable error. Do not trigger during feature work or refactors.
+---
+
+# Reference From Tags
+
+Documentation only — no executable changes.
+
+## Invariants
+
+- Read `reference/README.md`, `reference/_authoring/workflow.md`, and relevant area guides first.
+- Tag diff is source of truth; planning artifacts optional.
+- Extend and correct pages; do not wipe existing reference.
+
+## Workflow
+
+1. **Tags** — resolve base and target from human input and `reference/releases/index.md`. Ask if ambiguous.
+2. **Per area** — read `reference/_authoring/areas/<area>.md`; scope diff to area paths:
+   `git diff --name-status <base>..<target> -- <paths>`
+3. **Optional hints** — read `context/initiatives/*/release-doc-notes.md` when present; verify against diff.
+4. **Update** — area `README.md` and `features/*.md` for material behavior changes. Skip refactors, test-only, lint, dep bumps with no behavior change.
+5. **Record** — append row to `reference/releases/index.md`.
+6. **Validate** — `git diff --check`; confirm documentation-only diff; summarize.
+
+**Single-page/fix requests:** minimal edit to that page; verify against source.
+
+See `reference/_authoring/workflow.md` for audience, writing style, and diagrams.

package/template/AGENTS.md

@@ -0,0 +1,16 @@
+# Agent Guidance - PROJECT_NAME
+
+Area-specific `AGENTS.md` files layer on top of this one.
+
+<!-- reference-docs:start -->
+## Reference Docs
+
+Release-anchored reference under [`reference/`](reference/). Accepted behavior as of a release tag or baseline — not edited as a side effect of feature work.
+
+Authoring: [`reference/_authoring/`](reference/_authoring/README.md).
+
+Invocation-only skills — ask by name:
+
+- [`reference-from-tags`](.agents/skills/reference-from-tags/SKILL.md) — refresh from a tag-to-tag diff.
+- [`reference-baseline`](.agents/skills/reference-baseline/SKILL.md) — document current accepted behavior.
+<!-- reference-docs:end -->

package/template/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/template/reference/_authoring/README.md

@@ -0,0 +1,46 @@
+# Reference Authoring Guide
+
+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 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.
+
+## Area Guide Pattern
+
+Create one authoring guide per documented area:
+
+```text
+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 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
+- domain terms and cross-links specific to that area
+
+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
+reference workflow. Keep authoring rules in this subtree so the guidance
+has one source of truth.
+
+## Contributing
+
+Edits to this subtree usually belong with documentation workflow changes or
+release refresh work. If a project's documented area changes shape, update the
+matching authoring guide.

package/template/reference/_authoring/areas/README.md

@@ -0,0 +1,16 @@
+# Area Authoring Guides
+
+This folder contains one authoring guide per documented area.
+
+Create a guide from `_template.md` when adding a documentation area:
+
+```text
+reference/_authoring/areas/<area-slug>.md
+```
+
+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
+
+- None yet.

package/template/reference/_authoring/areas/_template.md

@@ -0,0 +1,65 @@
+# Area Name
+
+## Scope
+
+- Source orientation: `path/to/runtime-or-product-code`, `path/to/contracts`,
+  `path/to/tests`, `path/to/ci-or-delivery`, `path/to/infra-or-config`
+- Reference root: `reference/<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 | Reference page | Notes |
+| --- | --- | --- |
+| TBD | `reference/<Area>/features/<feature>.md` | TBD |
+
+## What Matters At Release Time
+
+Document behavior changes that affect:
+
+- user, operator, or API-visible behavior
+- permissions, validation, or error handling
+- data creation, mutation, retention, or migration
+- integrations or external contracts
+- observability, support, or operational procedures
+- configuration, environment shape, or deployment behavior
+
+## What To Ignore
+
+Ignore changes that do not alter released behavior:
+
+- pure refactors
+- internal renames
+- formatting or lint-only changes
+- test-only changes
+- dependency bumps with no behavior impact
+- temporary migration scaffolding that will not ship as behavior
+
+## Code Orientation
+
+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 `reference/_authoring/terminology.md`.
+
+## Cross-Links
+
+List related areas and when reference should cross-link instead of duplicating
+behavior.

package/template/reference/_authoring/terminology.md

@@ -0,0 +1,40 @@
+# Project Terminology
+
+Use this file to define the domain language that documentation should use.
+
+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.
+
+## Core Terms
+
+| Term | Meaning | Code-level names to translate |
+| --- | --- | --- |
+| TBD | TBD | TBD |
+
+## Relationships
+
+Use this section for named relationships between important domain concepts.
+
+| Relationship | Between | Meaning |
+| --- | --- | --- |
+| TBD | TBD | TBD |
+
+## Guardrails
+
+Capture wording rules that prevent misleading documentation.
+
+Examples:
+
+- Prefer one canonical term over an overloaded code name.
+- Avoid implying that a relationship is permanent when it can change.
+- Call out standards-driven terms that must remain as-is.
+
+## Diagram
+
+Add a Mermaid diagram when relationships are easier to understand visually.
+
+```mermaid
+flowchart LR
+    ConceptA["Concept A"] -->|"relationship"| ConceptB["Concept B"]
+```

package/template/reference/_authoring/workflow.md

@@ -0,0 +1,43 @@
+# Reference Workflow
+
+How `reference/` is structured, written, and refreshed. Area-specific paths live in [`areas/`](areas/).
+
+## When To Edit
+
+Only when a human explicitly asks: release refresh, baseline, a specific page update, or a demonstrable fix. Never as a side effect of feature work — flag staleness in `release-doc-notes.md` instead.
+
+## Modes
+
+**Baseline** — document current accepted behavior. Use `.agents/skills/reference-baseline/SKILL.md`. Record reference point in `reference/releases/index.md`.
+
+**Release-forward** — sparse start; refresh at tag time from diff. Use `.agents/skills/reference-from-tags/SKILL.md`. Optional hints from `context/initiatives/*/release-doc-notes.md`.
+
+## Cadence
+
+Refreshed once per accepted release, anchored to tag (default `release/vMAJOR_MINOR_PATCH`). Document custom tag conventions here before first refresh.
+
+## Audience
+
+Non-developer technical readers (QA, product, support, operators) unless the project defines otherwise. Behavior and rules in domain language; link to source for depth.
+
+## Layout
+
+```text
+reference/<Area>/
+  README.md
+  features/<feature>.md
+```
+
+Write from observable behavior outward. Mermaid for architecture/flow when clearer than prose; keep diagrams small.
+
+## Release Refresh (summary)
+
+1. Diff `<previous-tag>..<target>`, one area at a time per area guide.
+2. Update affected pages; ignore refactors and test-only changes.
+3. Append `reference/releases/index.md` row.
+
+Full steps: `.agents/skills/reference-from-tags/SKILL.md`.
+
+## Do Not Document
+
+Internal helpers, generated API docs (link instead), transient scaffolding, or open plans (those live in `context/`).

package/template/reference/_templates/area/README.md

@@ -0,0 +1,58 @@
+# Area Name
+
+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
+flowchart LR
+    User["User or operator"] -->|"uses"| Area["Area"]
+    Area -->|"reads or writes"| Data["Data store"]
+    Area -->|"calls"| External["External system"]
+```
+
+## Responsibilities
+
+- 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/template/reference/_templates/area/features/feature-template.md

@@ -0,0 +1,71 @@
+# Feature Name
+
+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
+
+## 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/template/reference/releases/index.md

@@ -0,0 +1,20 @@
+# Reference Release Index
+
+One row per tagged release. Tag names default to `release/vMAJOR_MINOR_PATCH`
+unless the project documents a different convention.
+
+Reference at a given tag describes the behavior of that release.
+
+| Tag | Date | Areas refreshed | Owner | Summary |
+| --- | --- | --- | --- | --- |
+| TBD | TBD | TBD | TBD | First documentation refresh. |
+
+## 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.
+- Keep the summary to one sentence. Link to an area or feature doc when a
+  change deserves more space.