Skip to content

AI-1296: Sync docs-md to codebase, reorganize, add docs-sync skill - #229

Merged
alex-struk merged 23 commits into
AI-1296from
AI-1296-docs-sync
Jul 7, 2026
Merged

AI-1296: Sync docs-md to codebase, reorganize, add docs-sync skill#229
alex-struk merged 23 commits into
AI-1296from
AI-1296-docs-sync

Conversation

@alex-struk

@alex-struk alex-struk commented Jul 3, 2026

Copy link
Copy Markdown
Collaborator

Summary

AI-1296

Stacks on #198 (repo wiki). Reorganizes docs-md/ from a flat dump into a topic-folder taxonomy, code-audits all 88 active docs against the codebase, syncs the wiki, adds a docs-sync maintenance skill, and fixes the drift found along the way.

Changes

Reorganization — docs-md/ moved into topic folders (architecture/ auth/ groups/ workflows/ extraction/ operations/ monitoring/ benchmarking/ frontend/) plus archive/ for point-in-time artifacts. 123 files moved with git mv; all references rewritten across code, READMEs, wiki, and the docs site (including the runtime template paths in apps/shared/prisma/seed.ts). New docs-md/README.md taxonomy index. Generated docs/wiki*.html untracked per #198's own rule.

Full code-verified audit (all 88 docs) — every concrete claim (paths, commands, env vars, endpoints, Prisma models, node/activity names, helm values) checked against code. Notable drift fixed:

  • BLOB_STORAGE: rewrote the stale key layout to the group-scoped scheme ({groupId}/{category}/...); removed the nonexistent classification container.
  • AUTHENTICATION: single findUserWithGroups identity query (not two); request.apiKey guard flow; IDOR "open issue" is resolved via group scoping.
  • OCR_CONFUSION_MATRICES/OCR_IMPROVEMENT_PIPELINE: derivation is the confusion-profiles module (docs claimed no API existed / a nonexistent endpoint).
  • ENRICHMENT: removed the deleted step-based config; dropped a nonexistent param.
  • WORKFLOW_NODE_CATALOG: added all registry activities missing from the catalog.
  • DAG_WORKFLOW_ENGINE: replaced the historical migration appendix listing files that never existed.
  • Plus many smaller corrections across groups/monitoring/operations/frontend docs.

Wiki sync — updated canonical_sources, sources.md, open-questions.md, log.md; added an extraction topic page (14 pages now validate green).

New docs-sync skill — .claude/skills/docs-sync/ with Ingest/Audit/AddDoc/Archive workflows, the topic taxonomy, and a repo-wide doc link checker. Wired into AGENTS.md, CLAUDE.md, and the PR template so docs stay in sync going forward.

Code fixes found during the audit (not docs):

  • Dockerfiles: build @ai-di/graph-workflow-config and @ai-di/temporal-payload-codec (both declared as file: deps but never copied — image builds from this branch would fail at npm install).
  • Removed dead GroupRequest.actorId frontend field.
  • Aligned stale instance-name tests + docstring with the deliberate 20-char truncation (31/31 pass).

Testing

  • npm run docs:wiki:check — green (14 wiki pages)
  • Repo-wide docs link checker — green
  • docs/build.sh — succeeds
  • Backend/temporal/frontend type-checks — green (also re-ran after regenerating the Prisma client, which was stale on this branch)
  • scripts/lib/instance-name.test.sh — 31/31

Checklist

By submitting this pull request, I acknowledge that I have attempted to meet the following:

  • a self-review of my code
  • commented code particularly in hard-to-understand areas
  • affected docs in the matching docs-md/ topic folder were updated (see docs-md/README.md; the docs-sync skill automates this)
  • if this changes system boundaries, doc routing, or where contributors should edit, the repo wiki (docs-md/wiki/) was updated or confirmed not needed
  • changes tested to the best of my ability
  • no new errors or non-functional code

🤖 Generated with Claude Code

alex-struk and others added 23 commits July 2, 2026 16:43
@alex-struk @claude
AI-1296: Add docs sync & cleanup design spec
1c44e8d 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Reorganize docs-md into topic folders, archive stale artifacts
e29f983 
- Move all active docs into topic folders: architecture/, auth/, groups/,
  workflows/, extraction/, operations/, monitoring/, benchmarking/, frontend/
- Merge graph-workflows/, workflow-builder/, temporal/ into workflows/
- Archive point-in-time artifacts (temp/ audits, rapid assessment, PR-88
  review, load test report, completed plans) under docs-md/archive/
- Rewrite all references across code, READMEs, wiki, and docs site
  (incl. runtime template paths in apps/shared/prisma/seed.ts)
- Add docs-md/README.md taxonomy index; expand archive/README.md policy
- Untrack generated docs/wiki*.html (gitignored per PR #198 rules)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Add docs-sync skill for docs-md/wiki maintenance
50d0834 
Encodes four workflows (Ingest after code changes, Audit accuracy,
AddDoc for gaps, Archive stale docs), the docs-md topic taxonomy, and
a docs-md-wide relative-link checker script. Referenced from AGENTS.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Docs audit fixes (batch 1: architecture, benchmarking, index)
f209ede 
Verified against code and corrected: audit event catalog, database
services map (Actor/Tables modules, method lists), HA resource values,
shared packages (7 packages, build chains, Dockerfile patterns), stress
run sheet preconditions, benchmarking analysis paths, README taxonomy.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Fix docs site index and README setup drift
e066777 
- Remove instructions referencing nonexistent .env.sample; point to
  manual .env creation and the external secrets override
  (docs-md/operations/local-dev-secrets.md)
- Update site index: project structure (ches-adapter, packages/, tools/),
  docs-md topic-folder references, wiki entrypoint link
- Rebuild docs/index.html via docs/build.sh

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Docs audit fixes (batch 2: extraction classifiers, patterns,…
650ae13 
… shared packages)

Verified against code: classifier deletion sequence (DB-first,
orphan-cleanup cron, exact config matching), upload caps, tables
pattern file layout and groupId injection, db-service module notes,
frontend vite alias caveat, stress-sheet matrix tracker note. Includes
partial edits from auditors interrupted by session limits; those docs
are re-audited in the follow-up run.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Docs audit fixes (batch 3: groups APIs, ground truth, operat…
7bff550 
…ions)

Groups API docs had several wrong endpoints (bulk-assign, get-all,
user-membership, leave, request-membership) replaced with actual
routes/authorization (@Identity guards, group-admin rules, audit
events, ephemeral request rows). Ground-truth/HITL dataset docs:
status values, payload shapes, reopen endpoint. Operations deploy
docs verified. Includes partial edits from interrupted auditors;
remaining verification tracked in the follow-up checklist.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Archive DATABASE_ROLES, fix dangling links, wiki sync, remai…
fac1635 
…ning-audit checklist

- Archive DATABASE_ROLES.md (removed Role/UserRole schema) with routing
  to current auth docs
- Fix remaining repo-root-style links in WORKFLOW_NODE_IO_MODEL_DECISION
  and OCR_CONFUSION_MATRICES; docs-md link checker now passes clean
- Wiki: log entry for the reorg+audit, open-questions follow-ups
  (AI-1296 Dockerfile package mismatch, extraction topic page, dead
  actorId field, instance-name test expectations)
- Add remaining-audit checklist (56 docs + gap scans) executable via
  the docs-sync skill / checklist-executor

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Audit architecture batch (BLOB_STORAGE, TABLES, TEMPLATE_MOD…
92a437a 
…ELS)

BLOB_STORAGE: rewrite stale key layout to the group-scoped scheme
({groupId}/{category}/... via @ai-di/blob-storage-paths), remove the
nonexistent 'classification' Azure container (training mirrors primary
keys), fix training container naming (training-{id}-v{n}), document
thumbnail.webp and _shared prefix. TABLES: add year-month column type.
TEMPLATE_MODELS: TRAINING_MIN_DOCUMENTS configurable minimum.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Audit HITL architecture + auth docs
b10ec46 
HITL_ARCHITECTURE and GROUP_RESOURCE_AUTHORIZATION verified accurate.
AUTHENTICATION: identity resolution is a single findUserWithGroups
query (not two parallel queries), ApiKeyAuthGuard sets request.apiKey
(not request.user/apiKeyGroupId), IDOR open issue marked resolved via
group-scoped authorization, test example matches MeResponseDto.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Audit LOAD_TESTING + extraction confusion/pipeline docs
55e8d37 
LOAD_TESTING verified accurate. OCR_CONFUSION_MATRICES: derivation is
now implemented (confusion-profile module + confusionProfileId on
ocr.characterConfusion) - replaced stale 'offline only' status.
OCR_IMPROVEMENT_PIPELINE: fixed nonexistent confusion-matrix/derive
endpoint (real route is groups/:groupId/confusion-profiles/derive),
removed dead OCR-TASK.md reference.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Audit extraction batch 2 (enrichment, field formats, normali…
aa92c15 
…zation)

ENRICHMENT: replaced legacy step-based (steps.enrichResults) config
with graph-node parameters; removed nonexistent llmPromptAppend param
(also from OCR_IMPROVEMENT_PIPELINE). FIELD_FORMAT_ENGINE: benchmark
mismatch integration is shipped, not TODO; documented suggestFromRun.
DOCUMENT_IMAGE_NORMALIZATION: blob prefixes updated to group-scoped
key scheme.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Audit frontend docs batch
6f2c67a 
Verified BC design system migration doc paths/adapters, screen
migration status table, and reference-data tables UI (fixed
TablesListPage component name).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Audit groups UI docs batch
b82120f 
SIDEBAR_NAVIGATION rewritten: routing is explicit createBrowserRouter
(not a catch-all), sidebar lives in RootLayout, GroupsPage is no
longer a placeholder. GroupSelector header location corrected.
Bootstrap, selector, membership page, context, and detail docs
verified against code.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Audit monitoring docs batches
507f2b1 
Helm/PLG, metrics/dashboards, and local/logging docs verified against
the plg chart, @ai-di/monitoring metric names, and compose profiles.
PROMETHEUS_HELM_CHART: Alertmanager IS included in the chart (stale
'metrics only' note removed). Stray docs/LOGGING.md (March 2026)
archived; monitoring/LOGGING.md is canonical.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Audit operations docs batches (verified accurate)
ae92d25 
Env/secrets and infra docs verified: all documented env vars exist in
code, manifests, or deploy scripts; referenced scripts and terraform
files resolve. Archived docs/LOGGING.md move included previously.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Audit workflows docs batches
7bacbd9 
DAG_WORKFLOW_ENGINE: verified all referenced paths and activity IDs;
replaced the historical migration Appendix A with a note (several
listed paths never existed or moved to graph-engine/ and packages/).
WORKFLOW_NODE_CATALOG: added registry-verified utility activities
section (blob.read, tables.lookup, document.* helpers, extractToBase64
blob-path note) and two missing benchmark rows. Remaining workflows
docs verified accurate.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Complete gap scan; add CI workflows overview
7557011 
Scanned backend/temporal/frontend/packages/ops/CI surfaces against doc
coverage. One substantive gap closed: docs-md/operations/CI_WORKFLOWS.md
mapping all 14 GitHub Actions workflows (QA, security scans, deploy,
manual DB ops, release). Wiki log updated; validator and link checker
green. Remaining-audit checklist fully checked off.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Build graph-workflow-config and temporal-payload-codec in im…
fb2b707 
…ages

Both apps declare @ai-di/graph-workflow-config and
@ai-di/temporal-payload-codec as file: dependencies, but neither
Dockerfile copied/built them, so the builder-stage npm install could
not resolve the file: paths. Add COPY + build (no @AI-DI inter-deps,
so no symlink needed) in the builder stage and COPY --from=builder in
the production stage of both Dockerfiles, matching the existing
workspace-package pattern.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Add Extraction wiki topic; point CLAUDE.md/PR template at do…
29d7b88 
…cs-sync

- New docs-md/wiki/extraction.md topic page routes the 11 OCR/extraction
  docs (index + sources registry updated); resolves the extraction-topic
  open question. Wiki validator now green over 14 pages.
- CLAUDE.md docs rule now names the topic-folder taxonomy and the
  docs-sync skill.
- PR template's documentation checklist item now names docs-md/ and the
  skill (alongside the existing wiki-routing item).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Fix dead frontend field and stale instance-name tests
2d5c499 
- Remove GroupRequest.actorId from useGroups.ts — the backend
  GroupMembershipRequestDto never returns it (dead optional field);
  frontend type-checks clean without it.
- Align instance-name tests with the deliberate 20-char truncation
  (the limit was changed 63->20 with a documented Crunchy-operator
  rationale, but tests 1.4/2.7 still expected pre-truncation values and
  2.8/2.9 were mislabeled '63'). Also fix the stale '63 characters'
  claim in the sanitize_instance_name docstring. Suite: 31/31 pass.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
AI-1296: Mark code findings resolved in docs-sync checklist
593dd26 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alex-struk @claude
Merge origin/AI-1296 into AI-1296-docs-sync; resolve conflicts
cb2d6aa 
Conflict resolutions:
- Dockerfiles (backend, temporal): drop graph-workflow-config COPY/build
  steps -- base removed that package (consolidated into graph-workflow).
- KUSTOMIZE_INSTANCE_TEMPLATE.md: keep the detailed HEAD wording but fix the
  annotation name ip_whitelist -> ip_allowlist to match the actual base Route
  manifests (route.yml uses ip_allowlist with the Silver/Gold/Gold DR NAT IPs).
- BC_DS_SCREEN_MIGRATION_STATUS.md: keep both the non-adapter-exceptions note
  and base's 2026-06-26 UI-consistency section (non-overlapping additions).
- CLAUDE.md: keep docs-sync skill + topic-folder guidance (matches reorg).
- PULL_REQUEST_TEMPLATE.md: keep docs-sync/topic-folder + wiki bullets, fold in
  base's READMEs / public docs/ site coverage.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@alex-struk
alex-struk marked this pull request as ready for review July 7, 2026 20:28
@alex-struk
alex-struk merged commit 3a5f911 into AI-1296 Jul 7, 2026
@alex-struk
alex-struk deleted the AI-1296-docs-sync branch July 7, 2026 20:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@dbarkowsky dbarkowsky Awaiting requested review from dbarkowsky dbarkowsky is a code owner
@antsand antsand Awaiting requested review from antsand antsand is a code owner
@NoorChasib NoorChasib Awaiting requested review from NoorChasib
@kmandryk kmandryk Awaiting requested review from kmandryk kmandryk is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@alex-struk