Docs ia

Architect the docs IA

A docs surface fails not because the atoms are bad but because the information architecture is — a 187-item alphabetical sidebar, no section overviews, raw directory names as labels, no "you are here," every page a dead end. The OKF atoms are already atomic (one concept per file); your job is to make the navigation and reading experience atomic too: every screen has one clear job, one obvious next step, and nothing dumped in a flat pile.

The North Star: the IA is a function of the graph. Dossier's atoms already carry typed edges (relates_to, uses, produces, stages, capabilities, delivered_by, systems, the client↔engagement↔capability spine). Hierarchy, ordering, and grouping must be derived from those edges and from concept type — never a hand-maintained list that drifts from the repo. Single-source-of-truth (CLAUDE.md), KB-agnostic (DEC-0015), read-only derived view (DEC-0001).

The five IA principles (enforce all five)

1. Atomic navigation — every nav node has ONE job. A group is a coherent set a reader holds in their head (~5–9 items, never 187). Split anything bigger by a real graph relationship, not by alphabet.
2. Progressive disclosure — orient → narrow → land. Top level is a handful of named zones; zones open into sections; sections open into atoms. A reader should reach any atom in ≤3 deliberate clicks and never face a wall of links.
3. Importance-first ordering — order by graph centrality (incident-edge degree), not A–Z. The hub a reader needs (rba-project-delivery-lifecycle, a service-line anchor) sits at the top of its group; long tails collapse.
4. Wayfinding, no dead ends — every page answers "where am I, what's around me, where next": breadcrumb (zone › section › atom), in-section prev/next, typed "Related concepts," and a path back to an overview. No atom is reachable only by URL.
5. Readable atoms — each page reads like a document, not a record: a strong first-sentence lead, a meta strip (type · confidence · source), scannable headings, and its relationships made visible.

The nav model — derive, don't author

Build the sidebar from the read KB (readKbAtoms() — full frontmatter incl. array edges), not from a flat dir walk:

• Zones (ordered, named super-sections) cluster concept types by reader intent. Default OKF→zone map (degrade unknown types into a trailing More zone so ANY KB still renders):
  • Start here — the KB root index.md overview + the highest-degree orienting atoms (the client/org anchor, the top-level delivery workflow).
  • Services & Capabilities — capability (sub-grouped by parent service line).
  • Delivery — workflow + process (processes nested under the workflow that stages/uses them; unattached processes in a "Standalone" subgroup).
  • Platforms & Systems — system (sub-grouped by vendor/platform where derivable).
  • Engagements & Clients — engagement + client.
  • People — role.
  • Reference — concept · term · policy · decision · artifact.
• Sub-grouping inside a big type set is the core win. A "hub" atom (high out/in-degree within its type, or one other atoms point at via relates_to/capabilities/stages/uses) becomes a subgroup; its neighbors nest under it. 187 capabilities → ~8 service-line subgroups. Cap subgroup depth at 2; never nest past zone › section › atom.
• Section overviews — every zone/section links to an overview page. Prefer a real index.md atom in that dir (author one if missing, see below); else synthesize the group label as a non-link header. A section must never be just a bag of leaves with no landing.
• Ordering — zones in the fixed intent order above; sections and atoms within them by descending degree, then title. Diátaxis lens (below) can re-badge but not reorder.
• Counts & collapse — show a count on each group (Capabilities · 187); collapse groups by default past the first zone so the sidebar opens calm.

The four page lenses (the "understand & read" half)

1. Wayfinding — breadcrumb from the zone path; in-section prev/next (Starlight pagination); a "↑ section overview" link. Implement once in the shared docs components, KB-agnostic.
2. Lead & scannability — the first body line must be a real lead sentence (≥8 words, not a heading); enforce via verify-kb/authoring. Keep the meta strip (type · confidence · source) at the top of every atom.
3. Related-concept surfacing — promote the typed-edge "Related concepts" block (already rendered by OkfRelated) and add a "see the neighborhood" link into /graph focused on this atom. Relationships are the moat — show them on every page.
4. Diátaxis lensing — tag each atom by reading intent so a reader can enter by what they're doing, not just by type. Derive a default lens from type (orient: index,client,workflow; how-to: process; reference: system,term,policy,artifact,role,capability; explain: concept,decision); allow an explicit intent: frontmatter override. Surface as a small badge; optionally offer a lens-filtered view.

Procedure

1. Diagnose — point at the KB (DOSSIER_KB), read it, and score it against the five principles. Name the specific failures with numbers (e.g. "Capabilities = 187 flat A–Z links; 0 section overviews; graph edges unused; no breadcrumb"). Reproducible, file-cited.
2. Derive the nav — implement/extend the graph-aware sidebar in @dossier/okf-view (the SSOT both surfaces consume). Keep it KB-agnostic with a flat-dir fallback so a sparse/unknown KB never breaks. Order by degree; sub-group by edges; cap depth.
3. Author the missing overviews — for each zone/section lacking an index.md, author one atomic type: index overview into the KB (faithful, provenance-stamped, links to that section's hub atoms). Root index.md is mandatory — without it the docs home (/knowledge/) 404s.
4. Wire the page craft — add breadcrumb + section nav + lens badge + neighborhood link to the shared docs components (@dossier/docs), never per-page.
5. Verify it ran — rebuild okf-view, serve the KB, and PROVE the new IA: /knowledge/ 200s with a real overview; the giant flat groups are gone; deep-links resolve; screenshot before/after. Then run on Dossier's OWN KB (default, no DOSSIER_KB) to confirm the dogfood docs still render — the generator must improve every KB, break none.

Guardrails

• Derived, never hand-maintained. No checked-in sidebar list. If the structure can't be derived, the atoms are missing edges — fix the graph (add the relationship), not the nav config.
• KB-agnostic or it's wrong. Test on ≥2 KBs (a client's + Dossier's own). Unknown types/dirs degrade gracefully into More, never a crash or a dropped atom.
• Sovereignty. The KB git repo is the source of truth; the sidebar/pages are a read-only derived view. Authoring an index.md overview INTO a client KB is legitimate (it's their KB's front page) — stamp it confidence: inferred with a real source, and don't restate sourced claims as first-party; link to the sourced atoms.
• Atomic to the end. One overview per section, one job per nav node, one source per fact. If a thing isn't atomic, organized, single-source — fix it or flag it.