Bootstrap the knowledgebase: site, diagrams, review pass, and restructure plan

.github/workflows/deploy.yml

@@ -0,0 +1,35 @@
+name: Deploy site (staging)
+
+on:
+  push:
+    branches: [main]
+    paths: ["knowledge/**", "site/**", "tools/prepare_site_content.py", ".github/workflows/deploy.yml"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: deploy
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('site/quartz.config.yaml') }}
+      - name: Build
+        run: bash site/build.sh
+      - name: Deploy to Cloudflare
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: deploy --config site/wrangler.jsonc --env staging

.gitignore

@@ -16,3 +16,9 @@ public/
 # tracked, despite the blanket `dist/` rule above.
 !site/okf-meta-plugin/dist/
 !site/okf-meta-plugin/dist/**
+viz.html
+.playwright-cli/
+
+# Raw source material reviewed for the bundle (may contain unpublished planning); never committed
+sources/
+.wrangler/

CHANGELOG.md

@@ -4,10 +4,18 @@ All notable reader-facing changes to this knowledgebase. Format follows [Keep a
 
 ## [Unreleased]
 
+### Changed
+
+- Tightened 112 knowledge pages and their navigation descriptions, reducing repetition while preserving examples and source extracts; a five-part review then restored qualifiers, disclaimers, and quoted source material the tightening had dropped, and reverted twelve pages.
+- Diagrams are Excalidraw-rendered SVGs composed for the text column, with click-to-zoom on the site; Mermaid is no longer used.
+
 ### Added
 
+- Source-grounded summaries of 15 project diagram boards, indexed by idea and pillar with links to the source material.
+- Reusable OIDM and Anatomic Locations logos for site content and diagrams, with the original style guide and usage notes.
+
 - First full draft of the knowledgebase: 115 documents in OKF 0.2 covering the overview and vision, a 48-term glossary, the semantic foundation (finding models, common data elements, anatomic locations, exam types, terminologies), the data structures (Observation, Exam Finding List, Imaging Problem List, Imaging Persona, FHIR and IHE alignment), the applications, the roadmap and open questions, project history, a repository map, and verbatim reference extracts.
 - Authoring guide, contributing guide, and migration ledger recording every document migrated from a working repository.
 - Two validation gates (OKF 0.2 conformance and house rules) run in continuous integration.
-- Rendered site built with Quartz and deployed to GitHub Pages, with frontmatter badges showing each document's type, status, provenance, and verification.
+- Rendered site built with Quartz and hosted on Cloudflare (dev, staging, and production targets), with frontmatter badges showing each document's type, status, provenance, and verification.
 - All documents are status draft pending the project lead's verification.

DEV_LOG.md

@@ -21,3 +21,40 @@ Engineering narrative for the oidm-knowledge repository: decisions, blockers, an
 - Phases 2 to 5 complete: six Opus agents wrote the semantic foundation, data structures, applications, and roadmap; each appended source conflicts to a collected file that became `roadmap/open-questions.md` (90 entries plus 21 upstream defects to file as issues). Project lead decisions applied: the taxonomies are the "MGB exam-oriented sub-taxonomies"; the next-generation vocabulary document is published as draft; the use case catalog is published with its committee credit.
 - Integration: ledger (118 rows) and log merged from agent scratch files; naming made consistent; a dead URL and an exam count corrected; both validators report 115 concepts, 0 errors, 0 warnings; the site rebuilds. Remaining Phase 6 work is the project lead's verification pass, then the first release entry and the follow-up issues (source-repo link-back PRs, upstream defect reports, manuscripts).
 - Added the project lead's stated goals verbatim to the plan so that documents citing the planning interview have a written source (open question 82).
+- Initial local commit made, marked pre-review. Added `Taskfile.yml` (`task check|build|serve|publish|viz`). `task publish` validates, builds Quartz with a bucket-specific config, rewrites internal links to explicit `.html` paths with `tools/flatten_site_links.py` (Quartz has no file-style link option; plain object storage has no clean-URL rewriting), and uploads to the Tigris bucket. Published at https://oidm-public.t3.storage.dev/oidm-knowledge/index.html and verified. Root index now carries a pre-review banner.
+- Bucket links, second pass: the first flattening only rewrote hrefs in the HTML, so links built in the browser (explorer sidebar, search results, graph node clicks) still pointed at extensionless URLs and returned 404 on the bucket. `tools/flatten_site_links.py` now also injects a small script into every page that applies the same rule at link creation and click time, and patches the emitted JavaScript so direct `window.location` navigations pass through it. Verified in a real browser against the bucket: sidebar click, search result click, and body links all resolve.
+- Diagrams: the project lead rejected Mermaid. Replaced all three Mermaid blocks (architecture, data-structure hierarchy, repository map) with Excalidraw diagrams built by small Python builders in `tools/diagrams/` (shared helpers in `excalib.py`), rendered to SVG through the Excalidraw library in a headless browser (`render_excalidraw.py`, module pinned to 0.18.0 after the unpinned esm.sh build broke), and iterated by viewing each render: architecture took three versions, the repository map four, the hierarchy two. The `.excalidraw` source sits beside each document with its SVG. Diagram iteration was delegated to a Sonnet agent after the first diagram.
+- Site: Quartz assumes a host that rewrites clean URLs; the bucket does not. A Starlight spike (file-style output, site-graph plugin for graph and backlinks) is running in the scratchpad; the choice of generator goes to the project lead for review before anything changes. New rule recorded: every tool selection is reviewed with the project lead first.
+- Sources: the project lead added seven manuscript and deck files to the bucket folder oidm-knowledge-sources; an agent is extracting and summarizing them into the gitignored `sources/bucket/`.
+- Repository review: both validators pass (115 concepts, zero errors or warnings), and the Quartz build succeeds for all 133 Markdown files. All concepts remain unverified drafts. Source inventories now exist for the imported manuscripts/decks and 15 Excalidraw canvases; integration remains outstanding. Recorded publishing workflow gaps, source-watching behavior, documentation discrepancies, and the absence of a configured Git remote in `docs/plans/repository-review.md`. Review only; no publishing or commits.
+- Concurrent editing: a Codex session is rewriting bundle documents in this working tree (112 documents, generated.by set to codex/gpt-6, prose tightened, descriptions changed, no warnings remaining after reconciliation). Per the project lead, that run proceeds first; structure and index reconciliation follow once it finishes. Rule for this session: never overwrite a document whose generated.by is another agent's.
+- Verification tooling added: `task verify -- <paths>` stamps a human verified entry and status stable; `task review-status` and `task review-list -- <dir>` report progress. The project lead starts verification on the stable areas (glossary, history, references, semantic foundation).
+- Remote created at github.com/openimagingdata/oidm-knowledge (public); the deploy workflow is disabled; a local pre-push guard blocks agent pushes of main, so the project lead pushes.
+- Editorial pass completed with three sub-agents using pstack `unslop` and `technical-writing`: 18 concepts shortened from 21,186 to 15,732 body words (25.7%). Synchronized index descriptions and retained examples, citations, and draft status. Cross-review restored qualifications lost during shortening. Scope and verification are recorded in `docs/plans/lean-content-pass.md`; no publishing or commits by this session.
+- Hosting decided by the project lead: a Cloudflare static site, extensible with Workers. Set up as an assets-only Worker (`site/wrangler.jsonc`, html_handling auto-trailing-slash, which matches Quartz's clean-URL links natively). Quartz stays the generator on maturity grounds after a survey of wiki and knowledge-graph tools found nothing else both mature and maintained; typed-edge graph is a plugin to write later. Retired the object-storage pipeline (link flattener, bucket publish script, GitHub Pages workflow) in favor of `task deploy` and `.github/workflows/deploy.yml` (cloudflare/wrangler-action; needs CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID secrets). First deploy waits on the project lead's `wrangler login`.
+- First Cloudflare deploy: https://oidm-knowledge-dev.talkasab.workers.dev, verified in a browser (clean URLs, sidebar, search, SVG diagrams, no console errors). Targets: dev (default), staging, prod as separate Workers via wrangler environments; `SITE_BASE_URL` sets Quartz's baseUrl per target at build time. The push-to-main workflow deploys to staging; production is a deliberate `task deploy:prod`.
+- Full editorial review completed after the project lead rejected the initial 18-page cutoff. Three agents and the main editor read the remaining 97 concepts, all 17 indexes, and the historical bundle log; 94 further concepts changed, with three concise glossary references retained. Across both passes, concept bodies total 108,656 → 94,944 words (12.6% reduction at the review snapshot). Cross-review restored technical constraints and checked the element-binding quotation against its pinned source. Coverage and unchanged-page reasons are in `docs/plans/lean-content-coverage.tsv`; results and count methodology are in `docs/plans/lean-content-full-review.md`. Both validators pass with zero errors or warnings, and whitespace checks pass. Concurrent hosting/tooling work was preserved; no commits or publication by this session.
+
+## 2026-09-22
+
+- Restructure planning with the Codex session via `docs/plans/`: Codex wrote `restructure-around-project-ideas.md`; this session wrote `restructure-joint-notes.md` and two idea inventories (`idea-inventory-semantic.md`, 46 ideas; `idea-inventory-structures-and-uses.md`, 41 ideas) from the repositories' design documents, plans, prompts, skills, and ADRs. The project lead withdrew an inventory-derived 41-page list: the structure is the human one (the original brief and the January deck), now four pillars (semantic foundation; data structures; applications and uses; SDKs and sample applications). Ideas mined from repository documents and prompts are the team's own ideas and enter as first-class content; only agent inference is limited to linking prose. `idea-placement.md` places all 87 inventoried ideas under the pillar pages by source kind.
+- Read the SIIM 2026 "Reports of the Future" deck (June 2026, public) directly, including its six figures, at the project lead's request. Its Patient Context / Foundation Context framing, three axes, "connective tissue" of relationships and external citations, "resolve, don't reinvent" SDK mechanism, and the ask now sit above the four pillars in the joint notes; a relationships-and-citations page was added to pillar 1. Reading recorded in `sources/bucket/REPORT.md` section 8; source-map rows added to the build plan. No drafting has started; page list awaits Codex's reply and the project lead's review.
+- Planning conversation with the Codex session, framed by Codex at the project lead's request, produced a shared understanding recorded in the joint notes: the source eligibility rule, "related representations" wording, the organizing method, and real deletion of redundant generated material. The project lead ruled during it: a CDE and a finding model are the same content in two collections with different review expectations, both moving to the CDE schema rewrite's classes; the OIFM reorganization around that graph is urgent; and the structure is five named pillars (Foundation Context, Data Structures, SDKs, Use Cases, Sample Applications), used by name. The "Observation Type" umbrella the sessions had floated is withdrawn. The joint notes now carry the decisions, the agreed outline with the current pages that collapse into each part, and next steps; the placement table is being re-sectioned under the five names; the build plan gained a 2026-09-22 decisions table. The ACR-RSNA-CDEs session was told the rulings. Still no drafting.
+
+
+- Codex completed three staged pillar drafts in `knowledge/drafts/`: Data Structures, Use Cases, and Sample Applications, totaling 2,704 body words excluding metadata and footnotes. Independent source review corrected coding guarantees, durable-identity claims, provenance review boundaries, and differing status vocabularies. Citations and pinned Git source paths check out; full bundle validation awaits the remaining Claude drafts and index reconciliation. Handoff is recorded in `docs/plans/restructure-codex-drafts.md`; source cross-review and page replacement remain pending. No commit or publication by this session.
+- Drafting, Claude side: seven pages staged under `knowledge/drafts/` (introduction, foundation-context, finding-models-and-cdes, anatomic-locations, exam-types, standards, sdks) by four Opus agents, each reviewed by the main session and corrected (inventory IDs removed from prose, agent inferences cut, the deck's own labels used, an internal board cited without its link, American spelling). Three independent source-fidelity reviews of the Codex drafts written to `sources/review/`. Bundle validates at 144 documents, 0 errors, 0 warnings. Committed on `bootstrap`; pull request #1 opened from `bootstrap` into a newly created `main`.
+
+- Codex completed the source-fidelity cross-review of all seven Claude drafts, with three agents assisting; findings are in `sources/review/drafts-<page>.md`. Claude pages were not edited by this session. Corrected the three Codex drafts and recorded dispositions, including unsupported review claims, in the corresponding response files. Key fixes cover the worked graph example, source-specific status and transport claims, live application links, and team evidence for built demonstrations. Revised bodies total 3,074 words. Strict OKF and bundle checks pass (144 documents, zero errors/warnings), with citation-ID and whitespace checks passing. Updated the drafting plan, joint handoff, and bundle log. Replacement remains separate; no commit or publication by Codex.
+
+## 2026-09-30
+
+- Imported 16 original OIDM and Anatomic Locations logo/mark assets from Tigris into `knowledge/assets/brand/`, plus the 2023 style guide and a source/checksum manifest in `docs/brand/`. Documented logo typography, colors, the guide's conflicting light-blue RGB and hex values, and usage in site content and Excalidraw builders. Site and diagram READMEs link to the notes. The local Quartz build passed and emitted all assets unchanged; both bundle validators, manifest integrity checks, SVG embedding checks, and whitespace checks passed. The asset import leaves theme and diagram application for a separate task. Plan: `docs/plans/2026-09-30-brand-assets.md`, complete.
+
+## 2026-10-01
+
+- Compared current OKF skills and toolchains, including lorsabyan and serradura, and qualified the earlier QMD suggestion. Ran 29 labeled external validator fixtures with baseline-policy warnings excluded: installed/current scaccogatto reported 13/19 problem cases and accepted 10/10 clean cases; lorsabyan reported 19/19 and accepted 10/10. Recorded the shared impossible-date crash, differing check scope, missing backfill agent payload, and unsafe index-prose rewriting. Actual-bundle trials exposed 15 repository-versus-bundle source-path warnings in the alternative validator. Findings and upstream reuse priorities are in `docs/references/okf-tooling-comparison.md`; no installation, bundle changes, commit, or publication.
+
+- Reviewed OKF tooling origins and current reuse options. All 13 installed skill files match upstream `scaccogatto/okf-skills` commit `d8393f3` byte for byte; custom code is the house checker, verification helper, and publishing integration. Recorded Google's canonical-repository move, available upstream MCP/CI support, QMD and Basic Memory tradeoffs, and metadata compatibility differences in `docs/references/okf-tooling-review.md`. Review plan complete. No tooling changes, commit, or publication.
+
+- Captured and visually reviewed all 15 unique Excalidraw boards in `links.txt` (17 URL occurrences). Native SVG/PNG exports, source contents, searchable text, and checksum metadata are in gitignored `sources/linked-diagrams/`; 15 source-grounded draft summaries and their index are staged in `docs/references/linked-diagrams/`. Three untouched SVG exports have normalized copies for XML compatibility. Verified coverage, image decoding, SVG parsing, 63 checksums, and local links; OKF conformance has zero errors, with 50 external-directory link warnings whose targets were checked separately. Plan `docs/plans/2026-10-01-linked-diagrams.md` is complete. The proposed layer migration, detailed reference conversion, and figure redraws await the owner's go; no bundle or presentation moves, upload, commit, or publication by this session.