# Sync AI Context — synchronize AI-critical documents across the repo

Synchronize all AI-critical documents in the repository so they consistently reflect the current project state: `.context/` artifacts, `package.json` scripts, and any project-specific facts that have drifted. This is a **multi-doc sync**, not a single-file refresh — every document that the AI reads at session start, or that humans consult as authoritative, is brought into alignment in one pass.

**Target**: $ARGUMENTS (leave blank to operate on the current repo)

---

## What this produces

A synchronized set of AI-critical documents. Every file in the sync scope is either patched in-place or confirmed unchanged. The sync never regenerates from scratch; it patches drifted facts while preserving structure, human prose, and stable rule sections.

**Sync scope:**

| File | Role | Notes |
|---|---|---|
| `README.md` | `anchor` | Human-facing entry point; synced from `package.json` scripts + project identity |
| `AGENTS.md` | `anchor` | Canonical repository instructions loaded natively by OpenCode/Codex and imported by Claude |
| `CLAUDE.md` | `compatibility-shim` | Must remain exactly `@AGENTS.md` plus one newline |
| `INSTALLER.md` | `supplementary` | Installation guide; patched when step count, commands, or prerequisites drift |
| `CONTEXT.md` | `anchor` | Context engineering reference (forward-looking target — include in scope as soon as it exists on disk) |
| `docs/agentic-quality-engineering.md` | `supplementary` | Vision + lifecycle overview; patched for command name, skill name, or path changes |
| `docs/onboarding.html` | `standalone-html` | Self-contained onboarding page (CSS + JS inlined, hand-maintained); patched for command names, quick-reference tables, and TL;DR mnemonic (see Step 3.5) |

The audit step (Step 1.5) may extend this list if it discovers additional qualifying files.

---

## Step 0 — Verify the cross-harness instruction contract

This repository has a fixed instruction topology. Do not auto-select another memory file:

| Surface | Contract |
|---|---|
| `AGENTS.md` | Canonical instruction body and only editable policy source |
| `CLAUDE.md` | Exact one-line import shim: `@AGENTS.md` plus final newline |
| `.agents/skills/` | Canonical skill source |
| `.claude/skills` | Generated alias; never edit through this path |

If `AGENTS.md` is missing, stop. If `CLAUDE.md` is not the exact shim, report structural drift and stop rather than copying instructions into it.

---

## Step 1 — Detect project state

Inspect what already exists. The set of present files determines mode.

```bash
# KATA architecture
ls tests/components/TestContext.ts tests/components/api/ApiBase.ts tests/components/ui/UiBase.ts playwright.config.ts 2>/dev/null

# Context files (Level 1 — project-wide)
ls .context/business/business-data-map.md .context/master-test-plan.md .context/business/business-feature-map.md .context/business/business-api-map.md 2>/dev/null

# Technical API types (generated by `bun run api:sync` from an OpenAPI spec, if present)
ls api/schemas/ 2>/dev/null

# Project identity
ls .context/business/business-model.md .context/business/domain-glossary.md .context/project-config.md 2>/dev/null
```

**Mode selection:**

| What exists | Mode | Action |
|---|---|---|
| KATA + at least one Level 1 context file | **Full Sync** | Patch all targets with real values |
| KATA only, no `.context/` | **Minimal Sync** | Patch all targets with `<<PLACEHOLDER>>` values |
| No KATA architecture | **Stop** | Tell the user to run `/project-discovery` first, then `/adapt-framework` to wire KATA to the target stack |

---

## Step 1.5 — Audit AI-critical documents

Before gathering information, discover ALL AI-critical documents in the repo using the following heuristic. Output a list of target files tagged with their role. This list drives the sync in Steps 3–5.

### Discovery heuristic

Run the following checks in order. A file qualifies if it matches ANY rule.

**Rule 1 — All-caps root files** (highest signal): files at the repo root whose stem is all uppercase.

```bash
find . -maxdepth 1 -type f -name "*.md" | while read f; do
  stem=$(basename "$f" .md)
  [[ "$stem" == "${stem^^}" ]] && echo "ROOT-CAPS: $f"
done
```

Examples that qualify: `README.md`, `AGENTS.md`, `CLAUDE.md`, `INSTALLER.md`, `CONTEXT.md`.

**Rule 2 — Docs explicitly referenced by AGENTS.md or any SKILL.md**: scan `AGENTS.md` and all `.agents/skills/*/SKILL.md` files for paths under `docs/`. Any file in `docs/` mentioned by name (not a directory) qualifies.

```bash
grep -rh "docs/[^ )\`\"]*\.md" AGENTS.md .agents/skills/*/SKILL.md 2>/dev/null \
  | grep -oP "docs/[^\s)\`\"']+" | sort -u
```

**Rule 3 — `.context/` skill outputs**: files owned by `project-context` modes `data`, `features`, `api`, and `test-plan`.

```bash
ls .context/business/business-data-map.md \
   .context/business/business-feature-map.md \
   .context/business/business-api-map.md \
   .context/master-test-plan.md 2>/dev/null
```

Note: `.context/` outputs are NOT patched the same way as anchor docs. They are regenerated by their owning `project-context` mode. This skill checks whether they exist and whether `AGENTS.md` correctly lists them; it does NOT rewrite their content.

**Rule 4 — High inbound reference density** (≥ 3 cross-references from canonical skills or alias metadata): scan `.agents/skills/**/*.md` and `.agents/compatibility/command-aliases.json` for file-path mentions, count per target, flag those with ≥ 3 references. Harness wrappers are generated transport adapters, not workflow sources.

```bash
grep -rho "[./][a-z][a-z0-9/_-]*\.\(md\|html\)" \
  .agents/skills .agents/compatibility/command-aliases.json 2>/dev/null \
  | sed 's|.*:||' | sort | uniq -c | sort -rn | awk '$1 >= 3 {print $2}'
```

**Rule 5 — Standalone HTML docs**: any `.html` file in `docs/` that is hand-maintained (CSS + JS inlined, no MD source pairing). These get the `standalone-html` role tag and are patched in place — never regenerated from any MD source.

```bash
find docs/ -name "*.html" -print
# Each match is a standalone-html target. They are NOT paired with any .md file —
# the HTML is the single source of truth.
```

### Role tags

Assign each discovered file one role:

| Role | Meaning | Sync behavior |
|---|---|---|
| `anchor` | Primary, always-referenced file (ROOT-CAPS or AI memory) | Always patched; patch failures are blocking |
| `supplementary` | Referenced by skills/commands but not always loaded | Patched for command/path/name drift; other prose preserved |
| `index` | `.context/` command outputs | NOT rewritten — existence only checked; AI memory "Context System" section updated to reflect reality |
| `standalone-html` | Self-contained HTML, hand-maintained (no MD source) | Edit HTML directly; preserve structural integrity (no CSS/JS regen) — see Step 3.5 |

### Output format (internal — used by Steps 3–5)

```
SYNC TARGET LIST:
- README.md                                   [anchor]
- AGENTS.md                                   [anchor]
- CLAUDE.md                                   [compatibility-shim]
- INSTALLER.md                                [supplementary]
- CONTEXT.md                                  [anchor — not yet on disk, skip this run]
- docs/agentic-quality-engineering.md         [supplementary]
- docs/onboarding.html                        [standalone-html]
```

**Extendability note for future maintainers**: to add a new document to the sync scope, either (a) ensure it matches one of the 5 rules above, or (b) add it explicitly to the "Sync scope" table in this command's header. Both approaches are equivalent — the audit picks up rule-matches automatically.

---

## Step 2 — Gather information

Read in priority order. Stop at the first source that answers each question — do not load everything.

**Priority 1 (project identity):**
- `.context/business/business-model.md`
- `.context/business/domain-glossary.md`
- `.context/project-config.md`

**Priority 2 (technical context):**
- `.context/business/business-data-map.md` — entities, flows, state machines
- `.context/master-test-plan.md` — what to test and why (business-risk lens)
- `.context/business/business-feature-map.md` — feature catalog, CRUD matrix, integrations
- `.context/business/business-api-map.md` — critical endpoints, auth flows, architecture behind the API
- `api/schemas/` — TypeScript types generated by `bun run api:sync` (only if an OpenAPI spec exists in the target)

**Priority 3 (live config):**
- `package.json` (scripts, dependencies)
- `playwright.config.ts` (projects, browsers, reporters)
- `.env.example` (variable names — never read `.env` itself)

Extract: project name, target app URLs, tech stack, main entities, critical APIs, top user journeys, available scripts, configured Playwright projects.

If `.context/` is empty, ask the user for the four minimum facts before proceeding:
1. Target project name
2. Application URL (staging/dev)
3. Tech stack (frontend / backend / database)
4. Top 3 user journeys

---

## Step 3 — Update each target document

Iterate over every file in the Sync Target List (from Step 1.5). For each non-`index` file, apply the **patch-in-place procedure** below.

### Patch-in-place procedure (applies to every target)

**This is a sync, not a regeneration.** Always read the file before touching it. Patch only the facts that drifted. Keep existing section order, headings, and any prose the user wrote. Do not reorder, rename, merge, or split sections you believe are redundant. Structure templates (below, per-file) apply **only when a file does not yet exist** — use them to bootstrap, then subsequent runs patch in place.

**What constitutes a "drifted fact":**
- Skill or legacy alias changed (e.g. `/refresh-ai-memory` → `sync-ai-context`)
- File path no longer exists on disk
- Script name no longer in `package.json`
- URL changed in `.context/` or `.agents/project.yaml`
- Section lists a `.context/` file as present but it no longer is (or vice versa)
- Skill or command table has a stale description

**What is NOT a drifted fact (do not touch):**
- Prose the user wrote beyond the immediate fact
- Section headings and their order
- Human-authored commentary, rationale, or examples
- Stable rule sections in `AGENTS.md` (§1 Critical Rules, §2 Behavioral Layer, §3 Orchestration Mode, §10 KATA Quick-Reference)

### Per-document preserve-lists

Different files have different sections that must never be rewritten. Apply the appropriate list for the file being patched.

**`README.md`:**
- Any prose block the user added that is not a facts table
- Section order and top-level headings

**`AGENTS.md` (canonical instructions — priority §0–§11 structure as of the structural refactor):**
- §0 Preamble ("THIS IS NOT A README")
- §1 CRITICAL RULES — ALWAYS APPLY (every rule, caveman-compressed — the count grows; never hardcode it)
- §2 BEHAVIORAL LAYER — HOW AI REASONS (4 UPPERCASE principles)
- §3 ORCHESTRATION MODE — PERMANENTLY ACTIVE (7-component briefing, execution patterns)
- §4 CONTEXT LOADING MAP — TASK → WHAT TO LOAD (preserve table SHAPE; rows may be patched)
- §5 SKILLS + COMMANDS + MCPs REGISTRY (3 tables — patched for command name changes via Step 4.5; updated manually when the skill/command set evolves)
- §6 TOOL RESOLUTION ([TAG_TOOL] pseudocode table + MANDATORY load-skill-first rule)
- §7 PROJECT VARIABLES — POINTER (pointer-only to `.agents/README.md` + `.agents/project.yaml`; never inline project values here)
- §8 AI BEHAVIOR DURING TESTING (4 numbered behaviors)
- §9 LOCAL CONTEXT (PBI folder layout)
- §10 KATA QUICK-REFERENCE (layer diagram + pointer to `test-automation/references/`)
- §11 GIT WORKFLOW — POINTERS (auto-loads `/git-flow-master`)

If a section listed here is missing from the file you're syncing, that is structural drift — STOP and surface it to the user. Do NOT recreate from this list; structural refactors are out of scope for `sync-ai-context`.

**`INSTALLER.md`:**
- Installation flow narrative and step numbers
- Any customization notes added by the repo owner

**`CONTEXT.md`** (when it exists — forward-looking target):
- All structural sections
- Only patch: command name references, file path references, and any description that explicitly says "auto-detected" that has now been detected

**`docs/agentic-quality-engineering.md`:**
- Vision statements, principles, and narrative sections
- Lifecycle diagrams and architecture ASCII art
- Only patch: command/skill tables and path references

**`docs/onboarding.html`:**
- The entire `<style>` block, the entire `<script>` block, the structural hierarchy (`<section>`, `<div>`, `<nav>`, `<aside>`, `<header>`, `<footer>`), CSS classes, `id` attributes, `data-*` attributes, SVG diagrams, and any `viewBox` / coordinate math
- Step-by-step prose and tutorial flow inside `<p>` blocks beyond the immediate fact
- Only patch: command names inside `<code>` elements, table cell descriptions, the "three confusing pieces" table, the TL;DR mnemonic line, the cheat-sheet quick-reference table, the footer's "Last updated" date, and the footer version label when bumping

### Security protocol (applies to ALL targets)

**Pre-write redaction (run before any Write):**

Scan the drafted content in-memory before touching disk:

1. **Credential patterns** — strings matching `/(password|secret|token|api[_-]?key|authorization)\s*[:=]\s*\S+/i`.
2. **Production URLs** — hostnames that resolve to the project's production domain (`{{WEBAPP_DOMAIN}}`) **outside** the Environment URLs table. Staging / dev / localhost hosts are fine.
3. **Shaped secrets** — JWTs (`eyJ...`), Atlassian API tokens (`ATATT...`), GitHub PATs (`ghp_...`, `gho_...`), AWS keys (`AKIA...`).

On any match:

1. Replace the literal with `<<REDACTED>>` (or `{your-{field-name}}` placeholder when the field is the point of the paragraph).
2. Keep a redaction log — `{file} · {line reference} · {what was redacted} · {why}`.
3. Surface the redaction log back to the user in the Step 6 report so they can decide whether it was a false positive.

A redaction never silently succeeds — the user must see what was removed before any file is written.

### `README.md` specifics

Sync the **Available scripts** section against `package.json` — do not invent scripts. The bootstrap template below applies only when `README.md` does not yet exist:

```markdown
# {Project Name} — Test Automation

> Test automation suite for {Target Project} ({repo URL})
> Built with **KATA Architecture** + Playwright + TypeScript

## Overview
{1-paragraph description of what this suite covers}

### Test coverage
| Type | Status | Description |
|---|---|---|
| E2E | ✅ / 🔄 | … |
| Integration (API) | ✅ / 🔄 | … |

## Tech stack
{Table: Playwright version, TypeScript, Bun, reporters, key MCPs}

## Quick start
{Install steps, env setup, first run command}

## Available scripts
{Tables for: Test Execution, Reports, Code Quality, Utilities — synced from package.json}

## Project structure
{Simplified `tests/` tree}

## KATA architecture
{One-paragraph explanation + link to adapt-framework and kata-architecture.md}

## AI-assisted development
{Reference to the AI memory file from Step 0 + a note about /project-discovery}

## Links
{Guidelines, target project, internal docs}
```

---

## Step 3.5 — Sync `docs/onboarding.html`

**Approach: text-only edits on a self-contained, hand-maintained HTML page. Never regenerate from any MD source — there is no MD source.**

**Rationale**: `docs/onboarding.html` is a `standalone-html` target. The CSS lives in an inlined `<style>` block, the navigation script lives in an inlined `<script>` block, and the document is the single source of truth for the onboarding tour (no paired Markdown). The sync touches only user-facing copy when it diverges from the canonical sources — `README.md`, `CONTEXT.md`, the `.context/` business maps, and `package.json` scripts — and never re-renders the page.

**Algorithm:**
1. Read `docs/onboarding.html` directly.
2. Identify drifted user-facing copy by cross-referencing the canonical sources gathered in Step 2 (`package.json` scripts, skill names from `.agents/skills/`, aliases from `.agents/compatibility/command-aliases.json`, paths from `AGENTS.md`'s Context Loading Map, environment URLs from `.agents/project.yaml`).
3. Apply text-only edits to user-facing copy: text nodes inside `<p>`, `<span>`, `<td>`, `<th>`, `<li>`, `<dt>`, `<dd>`, `<summary>`, `<code>` elements, plus the page `<title>` and the footer's "Last updated" line. When bumping the page after a substantive content change, also bump the footer version label (e.g. `v1.2` → `v1.3`).
4. Apply the security protocol (pre-write redaction) before writing.

**What to never touch:**
- The entire `<style>` block (inlined CSS).
- The entire `<script>` block (scroll-spy JS).
- Structural tags (`<section>`, `<div>`, `<nav>`, `<aside>`, `<header>`, `<footer>`, `<main>`, `<article>`).
- CSS classes, `id` attributes, `data-*` attributes, `role` attributes.
- SVG diagrams, including coordinate math, `viewBox` values, and `<path>` data.
- Anchor link `href` values (the section IDs are part of the structure).
- Any content that is NOT a drifted fact against the canonical sources.

**Process:**
1. Read `docs/onboarding.html` to know its current state.
2. For each canonical-source fact that the page exposes (command names, script names, path references, TL;DR mnemonic phrasing, cheat-sheet rows), check whether the HTML copy matches. If drifted → patch the minimum text node. If matched → leave it.
3. Do NOT reflow surrounding elements, do NOT collapse blocks, do NOT renumber sections.
4. Update the footer's "Last updated" line to today's date when ANY text node is patched in this run.
5. Apply the security protocol (pre-write redaction) before writing.

---

## Step 4 — Deep sync of the AI memory file

This step focuses on `AGENTS.md`. It receives a deeper sync than other supplementary files because §5 Registry and §4 Context Loading Map are derived from disk state. They MUST stay in lockstep with `.agents/skills/`, `.agents/compatibility/command-aliases.json`, and `package.json`.

**Important boundary**: `sync-ai-context` PATCHES facts inside the priority §0–§11 structure of `AGENTS.md`; it does NOT restructure. If §-numbering, section names, or section order have drifted from the §0–§11 contract, STOP and surface the structural drift. Never put those sections in `CLAUDE.md`.

**Do not**:

- Reorder, rename, add, or remove top-level sections (§0–§11).
- Rewrite prose the user wrote (especially §1 Critical Rules, §2 Behavioral Layer, §10 KATA Quick-Reference narrative).
- "Improve" formatting, collapse tables you think are redundant, or merge sections.
- Re-inline project values that are now externalized to `.agents/project.yaml` (project name, env URLs, project key, MCP server names, Jira URL).
- Re-inline scripts (Critical Rule #11 says READ `package.json` DIRECTLY — never paste script tables back in).

**Sections to refresh (facts inside fixed structure):**

- **§4 CONTEXT LOADING MAP** — verify each row's "Load skill" cell points to a skill that exists on disk under `.agents/skills/`. Add a row if a new workflow skill was added; remove a row if a workflow skill was deleted. Trigger-phrase prose stays untouched.
- **§5 SKILLS + COMMANDS + MCPs REGISTRY** — three tables synced from disk:
  - Skills table: one row per directory under `.agents/skills/` (one-line trigger + purpose from each `SKILL.md` description).
  - Compatibility aliases table: one row per entry in `.agents/compatibility/command-aliases.json`. `.claude/commands/` and `.opencode/commands/` are generated wrappers and must match the manifest; they never own workflow prose.
  - MCPs table: rows match the configured MCPs in `.mcp.json` (or `opencode.jsonc`).
- **§7 PROJECT VARIABLES — POINTER** — verify the pointer text still references the correct files (`.agents/README.md`, `.agents/project.yaml`). If `.agents/` was renamed or removed, patch the pointer. NEVER inline project values here.

**Sections to preserve verbatim** (per the §0–§11 preserve-list in Step 3):

- §0 Preamble
- §1 CRITICAL RULES — ALWAYS APPLY (ALL rules, whatever the current count, including #11 "SCRIPTS = READ `package.json` DIRECTLY")
- §2 BEHAVIORAL LAYER (4 principles, scope notes)
- §3 ORCHESTRATION MODE — PERMANENTLY ACTIVE (7-component briefing, execution patterns, exempt-skill list)
- §6 TOOL RESOLUTION (resolution table + MANDATORY load-skill-first rule)
- §8 AI BEHAVIOR DURING TESTING
- §9 LOCAL CONTEXT (PBI folder layout)
- §10 KATA QUICK-REFERENCE (layer diagram + hard rules + pointer)
- §11 GIT WORKFLOW (protected branches + critical commit rules)

**If the memory file does not yet exist:**

Do NOT bootstrap from inside `sync-ai-context`. Clone the full boilerplate repository. `AGENTS.md`, the `CLAUDE.md` shim, `.agents/skills/`, and compatibility tooling ship together. Once the contract exists, re-run `sync-ai-context` to align cross-doc facts.

Do **not** copy from a sibling project's instruction file. Downstream consumers are not sources of truth.

---

## Step 4.5 — Cross-doc consistency check

After all individual patches are computed (but before any file is written), verify cross-document consistency. If a fact appears in multiple documents, ALL copies must agree.

**Facts to cross-check:**

| Fact category | Documents to check | Example drift |
|---|---|---|
| Skill and alias names | All targets | `AGENTS.md` says `sync-ai-context`, onboarding still presents `/refresh-ai-memory` |
| `.context/` directory paths | `AGENTS.md`, `README.md`, `CONTEXT.md` | One file says `.context/business/`, another says `.context/mapping/` |
| Skill names | All targets | Skill renamed but not all docs updated |
| Environment URLs | `.agents/project.yaml` (source of truth), `README.md`, `docs/workflows/environments.md` | Staging URL changed in `.agents/project.yaml`, README + environments.md still show old. `AGENTS.md` does not inline env URLs. |
| Script names | `package.json` (source of truth), `README.md`, `docs/onboarding.html` | Script renamed in `package.json` but README + docs still show old. `AGENTS.md` Rule #11 forbids inlining script tables. |
| Instruction topology | `README.md`, `INSTALLER.md`, `docs/*` | A doc presents `CLAUDE.md` as canonical instead of the `AGENTS.md` source plus shim. |

**Drift detection algorithm:**
1. Extract each fact instance from each document.
2. If all instances match → mark `consistent`.
3. If any instance differs → mark `DRIFT DETECTED`, record `{fact} | {file A value} | {file B value}`.
4. Resolve all drift before writing any file — compute the patch for the lagging document in this step.

**Why this matters**: this cross-check is the mechanism that catches "you renamed a directory and now 12 files disagree." Run it every sync, not just when you suspect drift. It replaces the need for manual search-and-replace hunts across docs.

---

## Step 5 — Validate

Run all checks before reporting done. Checks apply to every file in the Sync Target List.

**Security check** — for each target file:
- [ ] No hardcoded passwords / API keys / tokens
- [ ] No production URLs with embedded credentials
- [ ] No personal emails (placeholders only)

**Reference check** — for each target file:
- [ ] Every script mentioned exists in `package.json`
- [ ] Every file path mentioned exists on disk (skip forward-looking references like `CONTEXT.md` if not yet created)
- [ ] Directory tree references match actual structure

**Consistency check** — across all targets:
- [ ] Project name matches across all documents
- [ ] Command names are identical across all references
- [ ] Environment URLs match across all files
- [ ] Tech stack matches `package.json` and `playwright.config.ts`
- [ ] `.context/` path references are consistent (all docs point to the same directory structure)

**`index` role files (`.context/` outputs):**
- [ ] For each `.context/` output that exists on disk, confirm the AI memory file's "Context System" section lists it.
- [ ] For each `.context/` output listed in the AI memory file but NOT on disk, flag it as `stale reference — remove from Context System section`.

---

## Step 6 — Report

After writing all files, report per-target outcome and any redactions.

```markdown
✅ AI memory sync complete

**AI tool detected**: {tool name}
**Mode**: Full Sync | Minimal Sync

**Sync results:**
| File | Outcome | What changed |
|---|---|---|
| README.md | updated | Available scripts table synced; project identity updated |
| AGENTS.md | updated | §4 Context Loading Map and §5 Skills + Compatibility Aliases tables synced with canonical disk state |
| CLAUDE.md | unchanged | exact `@AGENTS.md` compatibility shim verified |
| INSTALLER.md | unchanged | No drift detected |
| CONTEXT.md | skipped | File does not yet exist on disk |
| docs/agentic-quality-engineering.md | updated | Legacy command wording replaced by canonical skill/mode wording |
| docs/onboarding.html | updated | skill/alias text nodes synchronized; footer "Last updated" bumped |

**Cross-doc drift resolved:**
- {fact}: {old value} → {new value} in {N} files

**Sections preserved verbatim:**
- AGENTS.md: §0 Preamble, §1 Critical Rules, §2 Behavioral Layer, §3 Orchestration Mode, §6 Tool Resolution, §8 AI Behavior, §9 Local Context, §10 KATA Quick-Ref, §11 Git Workflow

**Security / redaction log:**
- {empty if none}
- {file · line · what was redacted · why}

**Suggested next steps:**
- Review the diff for any description that needs a human voice
- Confirm the Available Scripts section matches your team's actual workflow
- If CONTEXT.md now exists (created by Phase B), re-run `sync-ai-context` to include it
```

---

## Compression tooling — caveman-compress

When this skill rewrites memory documents (`AGENTS.md`, `CONTEXT.md`, README sections it owns, onboarding HTML, or owned docs pages), prefer running `caveman-compress <file>` BEFORE writing the new content if caveman is installed user-level. Never run it on the `CLAUDE.md` shim. caveman-compress preserves code blocks, URLs, and paths byte-for-byte while compressing prose ~46% on average. Re-runs are idempotent.

- Trigger: when the output is destined to be written to disk as a memory file.
- Skip when: the file is human-facing primary documentation that must stay verbose (e.g. CONTRIBUTING.md tutorial sections, INSTALLER.md, README.md user-facing intro).
- Verification: after compression, re-validate that all variable placeholders, code fences, and reference links survived (caveman-compress is byte-preservation-aware but a final grep is cheap insurance).
- Docs: <https://github.com/JuliusBrussee/caveman> (search "caveman-compress").

If caveman is not installed, write normal terse content. caveman-compress is enhancement, not requirement.

---

## Final checklist

- [ ] AI tool identified (Step 0)
- [ ] Mode selected based on project state (Step 1)
- [ ] AI-critical doc audit complete — Sync Target List produced (Step 1.5)
- [ ] Context read in priority order (Step 2)
- [ ] Each target patched in-place with real or placeholder values (Step 3)
- [ ] `docs/onboarding.html` text nodes updated, HTML structure (style/script/SVG) intact (Step 3.5)
- [ ] AI memory file deep-synced — facts refreshed, stable rules preserved (Step 4)
- [ ] Cross-doc consistency verified — all drift resolved before writing (Step 4.5)
- [ ] Security + reference + consistency checks passed across all targets (Step 5)
- [ ] Per-target outcome reported to user (Step 6)