From be086609764586d33b33357fba00b2a8bded683c Mon Sep 17 00:00:00 2001 From: Oliver Kieselbach Date: Tue, 21 Jul 2026 14:09:48 +0200 Subject: [PATCH] docs(claude): condense customer-facing claims and OKF sections CLAUDE.md ships with every request, so length is a running cost. Cut the new claims section from 12 lines to 4 and tightened the OKF section, dropping the spec URL and restating the rules imperatively. Net effect: the file is now smaller than before the claims section was added (654 words vs 856). No rules were removed - verify-before-writing, the change triggers, the durable-phrasing rule, and the operator-only-infra caveat all remain. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/CLAUDE.md | 26 +++++++++----------------- 1 file changed, 9 insertions(+), 17 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 00cf5332..10332544 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -71,24 +71,16 @@ Codex will review your output once you are done! ## Customer-Facing Claims -Four public surfaces make statements customers and security reviewers rely on. They drift silently because nobody opens them during a refactor — treat them as part of the change, not as documentation to update later. +`src/Web/autopilot-monitor-web/app/{about,terms,privacy}/page.tsx` and `autopilotmonitor-docs/trust/*` state facts customers and security reviewers rely on. They drift silently. -- **`src/Web/autopilot-monitor-web/app/about/page.tsx`** — marketing and tech-stack claims (framework and runtime versions, roles, integrations, agent deployment and lifecycle, diagnostics contents, isolation model). -- **`app/terms/page.tsx`** and **`app/privacy/page.tsx`** — plans and contracting, what is collected, retention, access, sub-processors, data residency. -- **`autopilotmonitor-docs/trust/security-faq.md`** and **`trust/subprocessors.md`** — the technical detail behind the two pages above; that repo's `index.md` carries its own sync rule and a "Last reviewed" date. +- Verify every claim against the code before writing it — never carry one forward because it was already on the page. +- Update them in the same change as: runtime/framework versions, roles, notification providers, agent deployment or lifecycle, diagnostics payload, isolation/delegation model, retention caps, sub-processors, or any default governing what is collected. +- Trust pages: durable phrasing over exact figures, and bump their "Last reviewed" date. Never advertise operator-only infrastructure (Telegram ops alerts) as a customer feature. -Rules: +## Technical Docs — OKF Bundle (`docs/`) -- Changing a runtime or framework version, a role, a notification provider, an agent deployment or lifecycle behaviour, the diagnostics payload, the isolation or delegation model, retention caps, sub-processors, or a **default that governs what is collected** means updating the affected surfaces in the same change. -- **Verify claims against the code before writing them** — never carry a claim forward because it was already on the page. Stale claims found in July 2026 included a ".NET 8" backend that was .NET 10, a non-existent "Next.js 18", ETL log collection that never happened, and "each tenant runs its own isolated instance" for a shared multi-tenant service. -- Prefer durable phrasing over exact figures on the trust pages, so routine tuning does not invalidate a published statement. -- Do not advertise operator-only infrastructure (e.g. Telegram ops alerting) as a customer feature. +Contributor/AI-facing docs (customer docs live in the `autopilotmonitor-docs` repo). Start at `docs/index.md` before opening individual files. -## Technical Docs — OKF Knowledge Bundle (`docs/`) - -`docs/` is an [Open Knowledge Format (OKF) v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) knowledge bundle for contributor/AI-facing technical documentation (customer docs live in the separate autopilotmonitor-docs repo). - -- **Consume first**: start at `docs/index.md` for progressive disclosure before opening individual documents. -- **When new durable technical knowledge emerges** (architecture decisions, flows, non-obvious mechanisms), capture it as an OKF concept document in `docs/` — markdown with YAML frontmatter: `type` (mandatory), plus `title`, `description`, `resource`, `tags`, `timestamp` (recommended). -- **Maintain the bundle**: add every new document to `docs/index.md`, note changes in `docs/log.md` (grouped by ISO date). Use standard RELATIVE markdown links between docs — never the OKF `/`-prefixed bundle-absolute form (GitHub resolves those from the repo root and navigation breaks). `index.md` and `log.md` are reserved filenames. -- Documents are English, structural markdown over prose (`# Schema`, `# Examples`, `# Citations` sections where applicable). \ No newline at end of file +- New durable knowledge (architecture decisions, flows, non-obvious mechanisms) → an OKF concept doc with YAML frontmatter: `type` (mandatory), plus `title`, `description`, `resource`, `tags`, `timestamp`. +- Register it in `docs/index.md`, note the change in `docs/log.md` (ISO date). `index.md` and `log.md` are reserved names. +- English, structural markdown (`# Schema`, `# Examples`, `# Citations`). Links between docs are RELATIVE — never `/`-prefixed, that breaks GitHub navigation. \ No newline at end of file