A

Hand-Rolled Documentation Machinery Critic

Goal: Critically audit /Users/rohan/Desktop/Projects/codealmanac/.almanac as documentation machinery to determine which taxonomy, page conventions, source provenance, link syntax, and gardening workflows should be preserved, simplified, removed, or redesigned.

Non-goals:

  • Do not edit implementation code.
  • Do not edit .almanac pages.
  • Do not treat the current wiki shape as justified just because it exists.
  • Do not recommend generic documentation patterns without explaining how they would move this wiki.

Executive Summary#

The .almanac documentation machinery should be kept. The core custom primitives are paying rent: flat markdown pages, stable slugs, a topic DAG, unified wikilinks, source frontmatter, file-aware retrieval, lineage metadata, and Build/Absorb/Garden as lifecycle operations. They are not accidental clones of a standard docs tree. They solve the product-specific problem of future coding agents needing grounded project memory before editing code.

The problem is that the custom system now has too many half-explicit conventions. Page jobs are intentionally not schema, but the wiki still relies on implicit anchors, informal hubs, optional status and verified fields, prompt-only page-shape doctrine, and docs that disagree about files: versus sources:. The result is a wiki with a healthy graph and a messy contract surface.

The strongest recommendation is not to replace Almanac's model with Diataxis, arc42, C4, ADRs, or a normal docs site. Those are good vocabularies, not the storage model. The right move is to wrap the custom wiki graph in a clearer organization doctrine: one front door, a few hub pages, canonical anchors, explicit merge/split/archive/redirect/no-op outcomes, and stricter source hygiene. That should happen in prompts and wiki conventions before it becomes TypeScript machinery.

The largest concrete quality issue is source provenance drift. I found 52 pages; all have title, summary, topics, and sources, but 30 pages still contain legacy string source entries inside sources: and one archived page still has legacy files:. There are 581 structured source objects and 136 legacy source strings. The migration is conceptually settled, but this wiki has not fully completed it.

The second concrete issue is navigation. prompts/operations/build.md, build-operation.md, operation-prompts.md, and almanac-serve.md all say getting-started.md is the canonical front door, but this wiki does not have .almanac/pages/getting-started.md. The graph has no broken page links in a direct parse, but a healthy graph is not the same thing as a readable first route.

Evidence Snapshot#

Inspected surfaces:

  • .almanac/README.md
  • .almanac/topics.yaml
  • .almanac/pages/*.md
  • prompts/base/notability.md
  • prompts/base/syntax.md
  • prompts/operations/build.md
  • prompts/operations/absorb.md
  • prompts/operations/garden.md
  • docs/concepts.md
  • docs/manual/good-codebase-wikis.md
  • README.md
  • guides/mini.md
  • guides/reference.md
  • /Users/rohan/Desktop/Projects/openalmanac/docs/ideas/codebase-wiki.md

Measured wiki state:

  • 52 markdown pages under .almanac/pages/.
  • 14 topics in .almanac/topics.yaml.
  • Every page has title, summary, topics, and sources.
  • 47 pages have verified; 5 do not.
  • 32 pages have status; 20 do not.
  • 2 pages have external_version.
  • 1 page has legacy files:.
  • 1 page is archived by archived_at and superseded_by.
  • Direct wikilink parse found 362 page links, 135 file links, and 15 folder links.
  • Direct wikilink parse found no broken page links.
  • Four pages had no inbound page links: hosted-deployment-environment, nessie, typescript-runtime-choice, and verification-workflow.
  • One page had no outbound page links: global-agent-instructions.
  • Largest pages by line count: github-native-wiki-maintenance at 831 lines, capture-automation at 726, wiki-organization-primitives at 397, almanac-serve at 387, and almanac-product-family at 320.

Structured source inventory:

  • file: 370
  • conversation: 100
  • web: 98
  • manual: 8
  • commit: 5

Legacy source inventory:

  • 30 pages contain string source entries inside sources:.
  • 136 total legacy string source entries remain.
  • sessionend-hook contains legacy files:.
  • superpaper has string sources only and no structured source objects.

Current Architecture Map#

The committed wiki source layer is:

  • .almanac/README.md: local notability bar, topic taxonomy, page shapes, writing conventions, and source expectations.
  • .almanac/topics.yaml: topic DAG metadata.
  • .almanac/pages/*.md: page source of truth.

The derived local layer is:

  • .almanac/index.db: SQLite projection over pages, topics, links, file refs, summaries, lineage, and page sources.
  • .almanac/runs/, .almanac/logs/, old root .capture-* and .bootstrap-* logs: local run artifacts, ignored by git.

The prompt doctrine layer is:

  • prompts/base/purpose.md: product purpose.
  • prompts/base/notability.md: what deserves pages, topics, clusters, and hubs.
  • prompts/base/syntax.md: frontmatter, sources, citations, wikilinks, writing conventions.
  • prompts/operations/build.md: first wiki construction.
  • prompts/operations/absorb.md: bounded source incorporation.
  • prompts/operations/garden.md: graph maintenance.

The public documentation layer is:

  • README.md
  • docs/concepts.md
  • guides/mini.md
  • guides/reference.md
  • docs/manual/good-codebase-wikis.md

The most important architectural fact: the source of truth is not one place. The wiki contract is spread across .almanac/README.md, prompts, guides, repo README, and implementation behavior. That spread is understandable for a fast-moving product, but it is now the main source of documentation machinery drift.

Prior Art Used For Comparison#

Diataxis is useful because it frames documentation around reader needs: tutorials, how-to guides, reference, and explanation. It should not become four top-level Almanac topics. Almanac's primary reader is an agent doing code work, so reader purpose should influence page leads and hubs rather than storage categories. Reference: https://diataxis.fr/

arc42 is useful because it names architecture communication sections: goals, constraints, context, solution strategy, building blocks, runtime, deployment, cross-cutting concepts, decisions, quality, risks, and glossary. Almanac already covers many of these as pages and topics. It should borrow this as a coverage checklist, not as a required folder or page template. Reference: https://arc42.org/overview

C4 is useful because it separates system context, containers, components, code, dynamic, and deployment views. Almanac should use that vocabulary when a page needs a view, but not add type: container-view frontmatter unless a query feature requires it. Reference: https://c4model.com/

Write the Docs' docs-as-code guidance supports Almanac's strongest choice: plain text, Git, code review, and docs integrated with product work. That argues for keeping repo-owned .almanac markdown rather than moving canonical memory into a hosted database. Reference: https://www.writethedocs.org/guide/docs-as-code/

Documenting Software Architectures is already represented by .almanac/pages/documenting-software-architectures.md. Its best contribution here is the "views and beyond" split: individual pages can answer different architecture questions, while shared beyond-view material gives rationale, glossary, review, currentness, and navigation.

Inventory And Recommendations#

1. Custom Topic DAG#

What is hand-rolled: .almanac/topics.yaml defines a multi-parent topic DAG. Pages assign topic slugs in frontmatter. Topics are reading neighborhoods rather than folders.

Evidence: The current taxonomy has 14 topics. The densest topics are agents with 25 pages, product-positioning with 18, cli with 17, systems with 13, flows with 13, and decisions with 13. The DAG gives agents two parents (flows, stack) and narrower cross-cutting topics such as provider-harness, prompt-system, and competitive-research.

Why it exists: The wiki needs multi-membership. A page like source-provenance is simultaneously wiki-design, storage, and decisions; a folder hierarchy would force one misleading primary home.

Standard comparison: Diataxis and arc42 are hierarchical presentation aids, not good storage models for cross-cutting codebase memory. C4 is a view vocabulary, not a taxonomy. A DAG is justified for agent retrieval.

Recommendation: Keep the topic DAG. Do not replace it with folders, Diataxis buckets, arc42 sections, or C4 levels.

Simplify: Narrow the overloaded agents topic. It currently mixes provider runtimes, operation prompts, source provenance, competitive products, product strategy, and wiki-design theory. The existing prompt-system, provider-harness, wiki-design, and competitive-research topics should absorb more of that meaning.

Wrap: Add a browse projection through hubs or a nav/front-door page. Topics should answer "what belongs together"; hubs should answer "what should I read first and why."

Confidence: High.

2. Page Type Conventions#

What is hand-rolled: The wiki uses page-shape vocabulary: Entity, Decision, Flow, Constraint, Failure Mode, Hub, Anchor, Subject Neighborhood, and similar terms. These are conventions, not enforced schema.

Evidence: .almanac/README.md says page shapes are suggestions. prompts/base/notability.md says genres are vocabulary, not enforcement. wiki-organization-primitives.md explicitly rejects subject: and type: frontmatter. operation-prompts.md calls the stray ## **type: runtime-view** heading in prompts/base/notability.md prompt debt.

Why it exists: The product wants agents to make editorial judgments instead of filling a rigid template.

Standard comparison: arc42 and C4 would be harmful if copied as page types. Their value is asking "which view does this reader need?" Diataxis has the same role. The page should be named for the subject and job, not for the template.

Recommendation: Keep page types as vocabulary. Do not add type: or subject: frontmatter unless a concrete query feature needs it.

Simplify: Remove the ## **type: runtime-view** prompt debt from prompts/base/notability.md in a future implementation pass. It conflicts with the settled "page naming before schema" rule.

Redesign: Make "page job" visible in leads and hubs. For example, capture-flow should read as the runtime flow anchor; capture-automation should read as the scheduler/product-contract anchor. The wiki should not require a hidden schema to tell those apart.

Confidence: High.

3. Source Provenance Model#

What is hand-rolled: sources: frontmatter stores page-local source IDs, types, targets, and notes. Citations use [@source-id]. The indexer derives page_sources and file refs. Legacy files: and string source entries remain supported.

Evidence: The current wiki has 581 structured source objects and 136 legacy source strings. Source types are mostly file, conversation, and web. There are no missing citation IDs in the direct parse, but 30 pages still have legacy string source entries. The source notes often say "Migrated from legacy files" or "Migrated from legacy sources," which is mechanically honest but weak as evidence.

Why it exists: Plain files: could only answer "what code does this page mention?" It could not answer "why should the reader believe this claim?" Structured sources also support web docs, conversations, commits, PRs, manual notes, and future issue/discussion sources.

Standard comparison: Docs-as-code does not solve provenance by itself; it gives versioned source files. Architecture docs need rationale and evidence, but standard templates do not provide CodeAlmanac's file-aware retrieval behavior. This custom model is justified.

Recommendation: Keep structured sources:. This is one of the strongest product primitives.

Simplify: Finish the legacy migration. The current wiki should not continue teaching future agents that string sources are normal. Run the deterministic migration in a future maintenance pass, then let Garden improve source notes and citations.

Redesign: Separate "sources inspected" from "sources that support claims." The largest pages have source lists that look like audit trails of everything an agent touched. A source list should contain evidence a future reader may need to inspect, not every input from the session.

Wrap: Add a source-quality gardening rule:

  • delete source entries not cited by any non-obvious claim unless they support general page context
  • replace "Migrated from legacy files" with a claim-specific note when the page is edited
  • prefer current code, tests, config, prompts, and public docs for present-tense claims
  • use conversations for rationale and history, not current behavior unless backed by current repo evidence

Research: Whether web sources need snapshots under .almanac/sources/ is still open. Do not add that machinery until shared-team verification requires it.

Confidence: High.

4. Legacy files: Compatibility#

What is hand-rolled: The wiki historically used files: frontmatter to power search --mentions. The newer source model derives file refs from sources[type=file], inline file wikilinks, and legacy files:.

Evidence: .almanac/README.md and prompts/base/syntax.md say sources: is canonical and files: is legacy. docs/concepts.md, guides/mini.md, and chunks of guides/reference.md still teach files: as central. The current wiki has one page with legacy files:: sessionend-hook.

Why it exists: Backward compatibility for existing wikis.

Recommendation: Keep read compatibility. Delete or rewrite instructional emphasis on files: everywhere current docs are meant to teach new behavior.

Delete candidate: Once migration has run across sample and real wikis, stop presenting files: in examples except in a compatibility section.

Risk: Removing read support too early would break existing wikis and search --mentions expectations. Do not remove parser support yet.

Confidence: High.

What is hand-rolled: One [[...]] syntax classifies page, file, folder, and cross-wiki links by content.

Evidence: The current page graph parse found 362 page links, 135 file links, 15 folder links, and no broken page links. .almanac/README.md, prompts/base/syntax.md, and the spec all document the same classifier.

Why it exists: The syntax gives agents one lightweight form that can express graph navigation and code references in ordinary prose.

Standard comparison: Markdown links cannot distinguish page slugs from repo file refs as a first-class index contract. Wiki engines usually support page links, but not CodeAlmanac's file/folder/source retrieval requirement.

Recommendation: Keep. This is a small, justified custom syntax.

Simplify: Prefer display text in prose where raw slugs interrupt reading. The syntax supports this, but some guide material still normalizes raw slugs too much.

Research: Do not add aliases or redirects through a second link syntax. If aliases become necessary, model them as lineage or redirect metadata resolved by the existing link form.

Confidence: High.

6. Gardening Workflow#

What is hand-rolled: Build creates the initial graph, Absorb incorporates bounded new context, and Garden improves the existing graph. Garden may merge, split, archive, retopic, relink, create hubs, or no-op.

Evidence: prompts/operations/garden.md gives a soft algorithm and explicitly allows broad graph edits. wiki-organization-primitives.md names create/update/merge/split/redirect/archive/no-op as structural outcomes. wiki-lifecycle-operations.md says operations are prompt-owned algorithms rather than proposal/apply pipelines.

Why it exists: The wiki drifts through content accumulation, not only through broken links. A deterministic health command can find graph integrity problems, but it cannot decide page scope, canonicality, or currentness of semantic claims.

Standard comparison: Docs-as-code expects ongoing maintenance and code review. Almanac's Garden is the agentic form of that maintenance loop. This is custom, but justified.

Recommendation: Keep Garden as an AI operation. Do not replace it with a TypeScript state machine.

Redesign: Make the Garden doctrine more operational. It should first inspect front door, hubs, oversized pages, orphan-ish pages, source-health warnings, stale source notes, and pages whose job is unclear. Today the prompt names those outcomes, but this wiki shows the front door and source migration can still drift.

Wrap: Use almanac health as deterministic preflight and postflight input for Garden, but do not make health mutate page prose.

Confidence: High.

7. Front Door And Hubs#

What is hand-rolled: getting-started.md is a prompt-level convention for the canonical wiki front door. Hubs are normal pages, not special storage objects.

Evidence: prompts/operations/build.md requires .almanac/pages/getting-started.md. build-operation.md, operation-prompts.md, and almanac-serve.md document the same convention. This wiki does not have .almanac/pages/getting-started.md.

Why it exists: Search and topics are not enough for first-read ergonomics. A future agent needs a ranked route through dense clusters.

Standard comparison: arc42 has a table of contents; C4 starts broad and zooms in; Diataxis is organized around reader tasks. Almanac should borrow that as a navigation habit while keeping graph storage.

Recommendation: Redesign the wiki's navigation surface, not the storage model.

Target shape:

  • Add getting-started.md as the front door in a future Garden run.
  • Add or strengthen hubs for wiki-design, lifecycle operations, provider harness, product positioning, and competitive research.
  • Keep hubs as normal pages with prose, sources, and links.
  • Do not add a parallel folder hierarchy as the canonical meaning model.

Confidence: High.

8. Page Size And Subject Boundaries#

What is hand-rolled: Subject neighborhoods are an editorial convention. There is no hard page size limit or page-splitting rule.

Evidence: github-native-wiki-maintenance has 831 lines. capture-automation has 726. wiki-organization-primitives has 397. These are not automatically wrong, but they are large enough that their sections now mix architecture, product contracts, incident lessons, backlog items, and open questions.

Why it exists: Absorb and Garden have favored append/update over split. That is often correct, but it can produce anchor pages that become hidden bundles of several page jobs.

Standard comparison: arc42 would split these across constraints, runtime, decisions, risks, and glossary. C4 would split static structure, dynamic flow, and deployment. Diataxis would split explanation from reference and task guidance.

Recommendation: Simplify through subject neighborhoods.

Candidate splits:

  • capture-automation: keep scheduler-backed quiet-session sync as anchor; split legacy hook cleanup, sync activation/backlog policy, cost-control incident, and manual smoke ladder if each remains useful.
  • github-native-wiki-maintenance: split remote product loop, GitHub App event model, hosted worker/sandbox substrate, OSS route, and buyer/payment thesis.
  • wiki-organization-primitives: keep as doctrine anchor; split repo browse projection or source/hub doctrine only if those topics continue to grow.

Risk: Splitting too eagerly creates thin pages. Split only when the subtopic has an independent reader question and enough links/sources.

Confidence: Medium-high.

9. status, verified, And Other Editorial-Only Metadata#

What is hand-rolled: Many pages use fields such as status, verified, and external_version. Current parser/query surfaces understand title, summary, topics, sources, archived_at, superseded_by, and supersedes; status, verified, and external_version appear to be editorial conventions rather than core indexed contracts.

Evidence: 32 pages have status, 20 do not. 47 have verified, 5 do not. 2 have external_version. prompts/base/syntax.md shows these fields in the example, but its next paragraph says the current tooling understands title, summary, topics, sources, archived_at, supersedes, and superseded_by.

Why it exists: The wiki wants currentness and lifecycle state to be inspectable.

Recommendation: Research and decide. Do not keep these as casual pseudo-schema forever.

Options:

  • Keep verified as an editorial date and teach Garden to update it only after checking sources.
  • Drop status except for proposed/implemented product-thesis pages where it is meaningful.
  • Add tooling only if queries like search --stale-verified or health --unverified-web-sources become necessary.

Risk: If verified is not maintained, it creates false confidence. A missing field is safer than a stale date that looks authoritative.

Confidence: Medium.

10. Public Docs Drift#

What is hand-rolled: There are multiple instruction surfaces for agents and humans: .almanac/README.md, guides/mini.md, guides/reference.md, docs/concepts.md, prompts/base/syntax.md, and root README.md.

Evidence: .almanac/README.md says structured sources: is canonical and legacy files: is only compatibility. docs/concepts.md still introduces files: as the frontmatter field. guides/mini.md still says frontmatter carries topics: and files: and tells writers to include files:. guides/reference.md contains both the new migration command and old files: examples.

Why it exists: The source-provenance model was added after the first public docs and guides.

Recommendation: Simplify the teaching surface. Make sources: the only first-class field in examples. Keep files: in a migration/legacy section.

Risk: Leaving this drift means future agents will continue creating legacy pages while the indexer and source-health system try to migrate away from them.

Confidence: High.

Legitimate Complexity Worth Preserving#

Keep these even though they are custom:

  • Flat .almanac/pages/ slug identity.
  • Topic DAG instead of folders.
  • Unified [[...]] syntax.
  • Source-derived file refs.
  • Structured sources: with page-local citation IDs.
  • Lineage fields for archival reversals.
  • Git as history.
  • index.db as derived local query cache.
  • Build/Absorb/Garden as prompt-owned lifecycle operations.
  • Health as deterministic report, not a mutating semantic fixer.

These are not solved by a standard docs site, ADR directory, C4 diagram set, or architecture template.

Accidental Complexity To Remove Or Contain#

Remove or contain these:

  • Legacy string sources in sources:.
  • Legacy files: examples in current teaching docs.
  • "Migrated from legacy files/sources" source notes when a page is next gardened.
  • The stray ## **type: runtime-view** heading in the notability prompt.
  • Oversized source lists that act as session audit trails rather than claim evidence.
  • Inconsistent status and verified fields unless they receive a clear maintenance contract.
  • Missing getting-started.md despite the prompt and viewer convention.
  • Topic overload where agents becomes a catchall for runtime, prompts, product research, and wiki theory.

Target Architecture For The Wiki#

The clean target is still a graph, not a tree:

.almanac/
  README.md             repo-local wiki constitution
  topics.yaml           topic DAG metadata
  pages/
    getting-started.md  canonical front door
    wiki-design.md      hub or anchor for wiki doctrine
    lifecycle.md        hub or anchor for Build/Absorb/Garden/sync/jobs
    provider-harness.md hub or anchor for runtime providers
    product-positioning.md hub for market/product pages
    <subject>.md        natural subject anchors

The page model:

---
title: Natural Subject Name
summary: One factual sentence that explains why an agent opens this page.
topics: [stable-topic, another-topic]
sources:
  - id: current-code
    type: file
    path: src/current/file.ts
    note: Supports the present-tense implementation claim.
  - id: rationale-session
    type: conversation
    path: /path/to/session.jsonl
    note: Records the rationale for the decision, not current code behavior.
verified: 2026-06-09
---

The editorial model:

  • Strong slugs and leads carry page identity.
  • Topics carry reading-neighborhood membership.
  • Hubs carry reading order and interpretation.
  • Sources carry evidence.
  • Wikilinks carry navigation.
  • Lineage carries conceptual reversals.
  • Git carries raw history.
  • Garden carries ongoing shape repair.

The anti-target:

  • Do not add rigid type: or subject: fields now.
  • Do not create a folder hierarchy that becomes the real taxonomy.
  • Do not make Diataxis, arc42, or C4 the storage model.
  • Do not create proposal/apply workflows for wiki edits.
  • Do not move canonical wiki memory into a hosted database.

Refactor And Gardening Roadmap#

Phase 0: Stop Teaching The Old Contract#

Goal: Make all current docs teach sources: as canonical.

Changes:

  • Update docs/concepts.md, guides/mini.md, and old examples in guides/reference.md to use structured sources:.
  • Keep files: only in a legacy compatibility section.

Why first: New writes should not create new legacy debt.

Risk: Low. This is documentation and prompt hygiene.

Verification: Search docs for files: and confirm only compatibility sections remain.

Phase 1: Complete Source Migration#

Goal: Remove legacy source shapes from this wiki.

Changes:

  • Run the deterministic legacy source migration in a future maintenance task.
  • Garden pages whose source notes still say "Migrated from legacy files/sources."
  • Keep conversations as rationale/history sources unless current code or docs support present-tense claims.

Why first: Source provenance is the trust model. It should be clean before major page rewrites.

Risk: Medium. Mechanical migration preserves body text, but source-note quality requires editorial judgment.

Verification: No legacy-frontmatter or unfixable-sources findings. No string entries in page sources:.

Phase 2: Add The Front Door#

Goal: Make the wiki readable from a first page.

Changes:

  • Add .almanac/pages/getting-started.md in a future Garden run.
  • Link to core hubs and anchors.
  • Explain read paths for common work: indexer/query, lifecycle operations, provider harness, sync/jobs, wiki design, product strategy.

Why first: This repo's own prompt contract already requires the page.

Risk: Low if it stays a map, not a duplicate architecture manual.

Verification: almanac serve home route has a page-backed front door. New agents can identify first reads without topic spelunking.

Phase 3: Split Or Hub The Largest Clusters#

Goal: Reduce bloated anchors without creating thin fragments.

Changes:

  • Treat capture-automation, github-native-wiki-maintenance, and wiki-organization-primitives as split candidates.
  • Create hubs only where clusters have multiple stable reader questions.

Why first: The longest pages are where architecture, history, incident, product, and open questions blur.

Risk: Medium. Bad splits create more navigation work.

Verification: Each split page has an independent reason to exist, sources, links, and a clear lead.

Phase 4: Define Or Delete Editorial Metadata#

Goal: Stop pseudo-schema from accumulating.

Changes:

  • Decide whether verified has a real maintenance policy.
  • Decide whether status is meaningful outside product/proposal pages.
  • Keep external_version only for external dependencies or references where version changes affect claims.

Why first: Metadata without semantics is worse than no metadata.

Risk: Medium. Some pages may use the fields as useful human signals even if tooling ignores them.

Verification: Every retained field has a documented meaning in .almanac/README.md or prompts/base/syntax.md.

Phase 5: Strengthen Garden Doctrine#

Goal: Make Garden a real graph editor, not a style cleanup pass.

Changes:

  • Add or strengthen organization doctrine in prompts.
  • Require Garden to check front door, hubs, canonical anchors, source hygiene, page size, topic overload, and pages without inbound or outbound links.
  • Keep no-op as a first-class successful outcome.

Why first: The current primitives are strong enough; the editor needs sharper priorities.

Risk: Low if it remains prompt guidance and does not become a deterministic state machine.

Verification: Future Garden runs produce fewer bloated pages, fewer weak source notes, and clearer hubs without adding schema.

Final Classification#

Keep:

  • Flat page graph
  • Topic DAG
  • Unified wikilinks
  • Structured sources and citations
  • File-aware retrieval
  • Lineage metadata
  • Build/Absorb/Garden operation split
  • Git-reviewed markdown source

Simplify:

  • Docs that still teach files:
  • Overloaded agents topic
  • Large pages that now contain several page jobs
  • Source lists that preserve raw session inventory rather than claim evidence

Delete candidate:

  • Legacy string source entries after migration
  • Stray type: runtime-view prompt heading
  • Casual status field if no maintenance/query contract appears

Replace with library:

  • None at the .almanac convention layer. This is not a solved-by-library problem. The existing use of standard YAML/markdown tooling in implementation is enough; the remaining issue is editorial structure.

Wrap:

  • Wrap the graph with hubs and getting-started.md.
  • Wrap prior-art vocabularies as guidance in prompts, not schema.
  • Wrap source hygiene with deterministic health plus Garden judgement.

Research further:

  • Whether web sources need snapshots.
  • Whether issue/discussion source types should become first-class in all docs.
  • Whether redirects/aliases need explicit metadata.
  • Whether verified should become a queryable currentness field.