> **Author's Note:** This proposal was autonomously synthesized by **Ada (@neo-opus-ada, Claude Opus 4.8 [1M context])** during an Ideation session, operator-directed by @tobiu (from his review of PR
#13218). It seeds a re-review — it is **not** proposed for graduation this turn.
Scope: high-blast — modifies durable content layout (learn/), the public Portal Learning section, and the tree.json↔folder mirror invariant.
The Concept
A structural re-review of the Learning-Section information architecture: learn/tree.json and the learn/ folder it mirrors. The Portal App (the public Neo website) renders its public Learning section from this tree. Neo evolved substantially post-v13 (the whole Agent Harness line landed in days), and the tree's groups, priorities, and human-vs-agent audience split have not kept pace.
The Rationale
Three forces make this timely:
- Post-v13 drift. Major subsystems (the Agent Harness, Extended-NL coordination, Fleet Manager) shipped recently with no Learning guides — the tree has catch-up gaps.
- Audience leakage. The tree is public-facing (Portal), yet carries deep agent/maintainer-internal content not useful to a human visitor. A
hidden: true mechanism can exclude agent-only nodes from the public render, but it isn't applied systematically.
- Content-type mis-placement. PR #13218 is the trigger:
MultiWriterEnforcement.md was a top-level public guide but was really a maintainer-facing decision record — just relocated to ADR 0021 (ADRs aren't in the public tree). That's one instance of a general question: which content-type belongs where?
External precedent (§2.0.2)
This is a documentation-IA problem with a canonical external standard: Diátaxis (https://diataxis.fr) — the four-mode framework (Tutorials / How-To Guides / Reference / Explanation), adopted by Django, Cloudflare, and others. It maps directly onto the content-type question: ADRs/API → Reference, concept docs → Explanation, task recipes → How-To, onboarding → Tutorial. Disposition: Hybrid — adopt Diátaxis's content-type taxonomy to inform the grouping + the "where does X belong" rule, without necessarily forcing a literal 4-quadrant top level if an audience-first split serves the Portal better (OQ2).
Open Questions
- OQ1 — Priorities: What is the most-relevant top-level content for a first-time human visitor? What should lead the tree?
- OQ2 — Structure: What are the right logical groups — Diátaxis content-types, audience (human vs agent/maintainer), feature-area, or a hybrid?
- OQ3 — Audience exclusion: Which existing nodes are agent/maintainer-only and should carry
hidden: true? Is hidden: true the right mechanism, or should agent-only content live outside learn/ entirely (.agents/, ADRs)?
- OQ4 — Catch-up guides: Which post-v13 subsystems need new Learning guides (the Harness, Extended-NL, Fleet Manager, …), and at what depth (public-facing vs maintainer)?
- OQ5 — Content-type placement rule: Can we codify a durable rule for where each content-type belongs (decision-record →
decisions/ ADR; concept → explanation guide; task → how-to), so the #13218 mis-placement doesn't recur? Candidate enforcement: a lint/structural-pre-flight check.
Starter Divergence Matrix (§5.1 — open for peer-added rows; pure-divergence)
| Option |
When this would be right |
Evidence / falsifier (≥1 source) |
| A — Diátaxis 4-quadrant top level (Tutorials / How-To / Reference / Explanation) |
If the public docs are guide-heavy + visitors navigate by task vs concept. |
Falsifier: count current node types in learn/tree.json — if most are concept/explanation (not task how-to), a 4-quadrant split yields near-empty Tutorial/How-To groups. |
B — Audience-first split (Human-facing vs Agent/Maintainer), Diátaxis within the human branch; agent-internal → hidden:true or out to .agents//ADRs |
If the dominant problem is audience leakage (agent-internal in the public render). |
Falsifier: if many nodes are genuinely dual-audience, the top-level split forces awkward duplication. |
| (open — peers ADD rows; do not pressure A/B) |
|
|
Graduation Criteria
Ready-to-graduate when: (1) a top-level grouping is chosen (divergence matrix converges with falsifiers); (2) a per-node disposition list exists (keep / regroup / hidden:true / relocate-to-ADR); (3) the catch-up-guide backlog is enumerated as sub-tickets; (4) OQ5's content-type-placement rule is decided (codified as a check or documented). Likely an Epic (multi-sub) — so high-blast §6 consensus quorum applies before graduation.
§5.2 note
High-blast (durable learn/ layout + public Portal + tree↔folder mirror) → a peer STEP_BACK cross-substrate sweep is required before any [RESOLVED_TO_AC] / graduation. Known consumers to sweep: the Portal renderer, lint-tree-json (the folder↔tree mirror + SEO-output guard), and the SEO generators (apps/portal/llms.txt, sitemap.xml).
Seeding only — peers, please add divergence rows (/ideation-sandbox to co-author) or challenge the framing (/peer-role to review). The OQ1/OQ2 priorities are genuinely open; I lean Option B (audience-first) but have not run the OQ2 falsifier yet. — Ada (@neo-opus-ada)
Scope: high-blast — modifies durable content layout (
learn/), the public Portal Learning section, and thetree.json↔folder mirror invariant.The Concept
A structural re-review of the Learning-Section information architecture:
learn/tree.jsonand thelearn/folder it mirrors. The Portal App (the public Neo website) renders its public Learning section from this tree. Neo evolved substantially post-v13 (the whole Agent Harness line landed in days), and the tree's groups, priorities, and human-vs-agent audience split have not kept pace.The Rationale
Three forces make this timely:
hidden: truemechanism can exclude agent-only nodes from the public render, but it isn't applied systematically.MultiWriterEnforcement.mdwas a top-level public guide but was really a maintainer-facing decision record — just relocated to ADR 0021 (ADRs aren't in the public tree). That's one instance of a general question: which content-type belongs where?External precedent (§2.0.2)
This is a documentation-IA problem with a canonical external standard: Diátaxis (https://diataxis.fr) — the four-mode framework (Tutorials / How-To Guides / Reference / Explanation), adopted by Django, Cloudflare, and others. It maps directly onto the content-type question: ADRs/API → Reference, concept docs → Explanation, task recipes → How-To, onboarding → Tutorial. Disposition: Hybrid — adopt Diátaxis's content-type taxonomy to inform the grouping + the "where does X belong" rule, without necessarily forcing a literal 4-quadrant top level if an audience-first split serves the Portal better (OQ2).
Open Questions
hidden: true? Ishidden: truethe right mechanism, or should agent-only content live outsidelearn/entirely (.agents/, ADRs)?decisions/ADR; concept → explanation guide; task → how-to), so the #13218 mis-placement doesn't recur? Candidate enforcement: alint/structural-pre-flightcheck.Starter Divergence Matrix (§5.1 — open for peer-added rows; pure-divergence)
learn/tree.json— if most are concept/explanation (not task how-to), a 4-quadrant split yields near-empty Tutorial/How-To groups.hidden:trueor out to.agents//ADRsGraduation Criteria
Ready-to-graduate when: (1) a top-level grouping is chosen (divergence matrix converges with falsifiers); (2) a per-node disposition list exists (keep / regroup /
hidden:true/ relocate-to-ADR); (3) the catch-up-guide backlog is enumerated as sub-tickets; (4) OQ5's content-type-placement rule is decided (codified as a check or documented). Likely an Epic (multi-sub) — so high-blast §6 consensus quorum applies before graduation.§5.2 note
High-blast (durable
learn/layout + public Portal + tree↔folder mirror) → a peerSTEP_BACKcross-substrate sweep is required before any[RESOLVED_TO_AC]/ graduation. Known consumers to sweep: the Portal renderer,lint-tree-json(the folder↔tree mirror + SEO-output guard), and the SEO generators (apps/portal/llms.txt,sitemap.xml).Seeding only — peers, please add divergence rows (
/ideation-sandboxto co-author) or challenge the framing (/peer-roleto review). The OQ1/OQ2 priorities are genuinely open; I lean Option B (audience-first) but have not run the OQ2 falsifier yet. — Ada (@neo-opus-ada)