scriptoriumadmin/fabro
1
0
Fork 0
mirror of https://github.com/fabro-sh/fabro.git synced 2026-09-06 08:18:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 11
fabro/.chisel/cartography/work/docs.md
Bryan Helmkamp 6bb6b5efcc
Add codebase cartography map
2026-07-27 10:15:42 -04:00

16 KiB
Raw Permalink Blame History

Documentation cartography scout

Assessed revision: 2bcf94fed8a9b429f18d9196fa824711d6f4cb0a

Instructions read: AGENTS.md, CONTRIBUTING.md, and the Chisel cartography prompt. Scope is every tracked file under docs/**, plus README.md and install.md.

Inventory

There are 488 scoped tracked files:

Area Files
docs/public/** 253
docs/internal/** 82
docs/plans/** 88
docs/brainstorms/** 11
docs/ideation/** 3
docs/superpowers/** 49
README.md, install.md 2

Proposed components

public-documentation — Public documentation

  • Purpose: Own the authored Fabro user documentation, Mintlify presentation/configuration, repository landing page, and the maintenance procedure for published web screenshots.
  • Globs:
    • README.md
    • docs/public/**
    • docs/internal/updating-web-screenshots.md
  • Exclude globs:
    • docs/public/api-reference/fabro-api.yaml — separate source contract
    • docs/public/changelog/** — separate published release-history component
    • all 22 generated public Graphviz SVG globs listed under exclusions below
  • Entry points:
    • README.md
    • docs/public/docs.json
    • docs/public/getting-started/introduction.mdx
    • docs/public/getting-started/quick-start.mdx
    • docs/internal/updating-web-screenshots.md
  • Owns:
    • Mintlify theme, navigation, tabs, and page ordering
    • public concepts, guides, tutorials, administration material, and reference prose
    • public documentation images, manually maintained SVG illustrations, logos, syntax definitions, and curated web screenshots
    • repository-facing overview and documentation links
    • web-screenshot capture and verification workflow
  • Depends on candidates: fabro-http-api-contract, documentation-demo-workflows, the CLI/config components that refresh fenced reference regions.
  • Evidence:
    • AGENTS.md:46-51 mounts docs/public as the Mintlify document root.
    • docs/public/docs.json declares the Mintlify schema, theme, navigation, OpenAPI tab, and changelog tab.
    • README.md links to docs.fabro.sh and embeds assets from docs/public/images and docs/public/logo.
    • docs/internal/updating-web-screenshots.md names docs/public/images/web/ as the screenshot destination, maps files to UI routes and doc consumers, and defines the refresh/verification workflow.
    • lib/foundation/fabro-dev/src/commands/docs.rs exposes cargo dev docs refresh/check; docs_cli_reference.rs and docs_options_reference.rs update only fenced regions of docs/public/reference/cli.mdx and docs/public/reference/user-configuration.mdx. The two whole files remain assigned here because substantial prose outside those fences is authored.
    • test/docs/extract_dots.py extracts workflow examples from the public docs for validation.
  • Assigned count: 112: 110 public-site files after the API contract, changelog, and 22 generated SVGs are removed, plus README.md and the screenshot-maintenance guide.

public-release-history — Published changelog

  • Purpose: Preserve and publish dated user-facing release/change records independently of current reference documentation.
  • Globs: docs/public/changelog/**
  • Entry points: docs/public/docs.json changelog navigation; newest page at the assessed revision is docs/public/changelog/2026-07-25.mdx.
  • Owns: dated titles, migration warnings, feature summaries, and historical behavior notes.
  • Depends on candidates: public-documentation for Mintlify navigation/presentation.
  • Evidence:
    • docs/public/docs.json gives changelog its own top-level tab and lists every dated page.
    • The 120 docs.json changelog page entries exactly match the 120 tracked MDX files.
    • Each page has date/title frontmatter and describes changes for that date.
    • lib/apps/fabro-server/tests/it/api/docs.rs:45-50 deliberately reads a changelog page as historical documentation.
  • Assigned count: 120.

fabro-http-api-contract — Fabro HTTP API contract

  • Purpose: Define the OpenAPI-first wire contract used by the server, generated clients/types, conformance tests, and published API reference.
  • Globs: docs/public/api-reference/fabro-api.yaml
  • Entry points: docs/public/api-reference/fabro-api.yaml
  • Owns: HTTP routes, request/response schemas, authentication declarations, and API-facing wire documentation.
  • Depends on candidates: none at the documentation layer; parent reconciliation should make its consumers depend on this component.
  • Consumers / evidence:
    • AGENTS.md:55-61 explicitly calls this file the source of truth and documents the Rust and TypeScript regeneration workflow.
    • lib/foundation/fabro-api/build.rs:159 consumes it for Rust generation.
    • lib/packages/fabro-api-client/package.json:7 consumes it for TypeScript Axios generation.
    • lib/apps/fabro-server/src/server/handler/system.rs:694 embeds it in the server.
    • lib/apps/fabro-server/tests/it/openapi_conformance.rs:21 reads it for route/spec conformance.
    • docs/public/docs.json points Mintlify's API tab at it.
  • Assigned count: 1.

documentation-demo-workflows — Executable documentation demos

  • Purpose: Provide runnable workflow definitions and supporting configuration/prompts used by public tutorials and demonstrations.
  • Globs:
    • docs/internal/demo/*.fabro
    • docs/internal/demo/*.toml
    • docs/internal/demo/prompts/**
  • Exclude globs:
    • docs/internal/demo/*.svg
    • docs/internal/demo/*.png
  • Entry points:
    • docs/internal/demo/01-hello.fabro
    • docs/internal/demo/14-search-imagegen.toml
    • tutorial commands of the form fabro run docs/internal/demo/<name>.fabro
  • Owns: small executable example graphs, the image-generation demo run config, and shared demo prompt text.
  • Depends on candidates: CLI runner, workflow engine/validator, agent tools, and configured sandbox/model providers.
  • Evidence:
    • Public tutorials such as docs/public/tutorials/hello-world.mdx, parallel-review.mdx, multi-model.mdx, plan-implement.mdx, and ensemble.mdx invoke these paths directly.
    • docs/public/core-concepts/models.mdx:250-251 also uses these graphs as runnable model examples.
    • docs/internal/demo/14-search-imagegen.toml selects its graph, Daytona environment, snapshot, and output assets.
    • .fabro files are complete Graphviz workflow entry documents with goal, start, and exit nodes.
  • Assigned count: 16 (14 .fabro, one .toml, one prompt).

internal-engineering-guidance — Active engineering policies and architecture references

  • Purpose: Record active repository-wide engineering policies and maintained architectural/runtime contracts that guide implementation changes.
  • Globs:
    • docs/internal/*-strategy.md
    • docs/internal/*-policy.md
    • docs/internal/events.md
    • docs/internal/fabro-event-schema-v2-concrete-shape.md
    • docs/internal/llm-client-resolution.md
    • docs/internal/run-directory-keys.md
  • Entry points:
    • AGENTS.md:136-146
    • docs/internal/events-strategy.md
    • docs/internal/testing-strategy.md
    • docs/internal/error-handling-strategy.md
  • Owns:
    • logging, events, testing, migrations, secret handling, error handling, React-effect, and panic policies
    • the maintained event catalog and implemented V2 event design explanation
    • LLM client-resolution rules, parallel-execution semantics, and run scratch-file reference
  • Depends on candidates: the runtime, server, CLI, web, configuration/auth, and workflow components whose contracts it describes. These are documentation dependencies rather than build edges.
  • Evidence:
    • AGENTS.md:136-146 makes seven strategy/policy documents mandatory reading before related changes.
    • docs/internal/events-strategy.md distinguishes durable product events from tracing and identifies their consumers.
    • docs/internal/events.md is the maintained serialized event catalog and was updated near the assessed revision.
    • docs/internal/fabro-event-schema-v2-concrete-shape.md:5 says Status: implemented; it also says the hand-written Rust types, not this document, are the actual contract source of truth.
    • docs/internal/parallel-strategy.md:3 says Status: implemented and was updated with the shared-checkout behavior at the assessed revision.
    • lib/foundation/fabro-vault/src/store.rs:359 links implementation documentation back to docs/internal/migrations-strategy.md.
  • Assigned count: 13.

product-context — Internal product framing

  • Purpose: Maintain concise product intent, audience, current shape, success signals, and stable technical/product constraints.
  • Globs: docs/internal/product/**
  • Entry points:
    • docs/internal/product/product-description.md
    • docs/internal/product/current-state.md
  • Owns: business problem, personas, product description, current-state snapshot, success metrics, and product-level technical requirements.
  • Depends on candidates: none as a build edge; it informs product and documentation work across the repository.
  • Evidence:
    • The six documents have complementary named roles rather than dated implementation tasks.
    • docs/internal/product/current-state.md explicitly describes a deliberately brief current product snapshot.
    • docs/internal/product/technical-requirements.md explicitly calls its contents stable constraints product changes should respect.
  • Assigned count: 6.

Cross-scope assignment

install.md -> marketing-site component

  • Count: 1.
  • install.md is a tracked mode-120000 symlink to apps/marketing/public/install.md.
  • Commit 0cc02c294dac23e3ace7646528431e758e37eea1 states that Vercel deploys the marketing subtree, so the real file lives there and the repository-root path is a symlink.
  • apps/marketing/src/pages/index.astro advertises https://fabro.sh/install.md.
  • The root alias should therefore be claimed by the component that owns apps/marketing/public/install.md, rather than by public-documentation.

Evidence-backed exclusions

Historical brainstorm, plan, audit, and design records — 159 files

These are point-in-time requirements, ideation, implementation plans, handoffs, one-time QA instructions, measurements, audits, or superseded proposals. They remain useful history but are not active source contracts or maintained policy components.

Glob/path Count Evidence
docs/brainstorms/** 11 Dated *-requirements.md brainstorm artifacts.
docs/ideation/** 3 Dated ideation records.
docs/plans/** 88 Dated implementation plans and handoffs.
docs/superpowers/plans/** 45 Dated execution plans.
docs/superpowers/specs/** 4 Dated feature/design specs.
docs/internal/cargo-target-apfs-churn-plan.md 1 Checkbox execution plan with an unfilled results section.
docs/internal/cli-workflow-coupling-audit.md 1 Snapshot audit organized around completed and remaining couplings.
docs/internal/event-schema-competitive-analysis.md 1 Dated comparative research report.
docs/internal/fabro-event-schema-v2-proposal.md 1 Explicit Status: proposal; the implemented concrete-shape document supersedes its framing.
docs/internal/mcp-server-qa-test-plan.md 1 Explicitly says it is a one-time manual QA pass, not a reusable testing template.
docs/internal/plan-events-as-source-of-truth-follow-ups.md 1 Prerequisite implementation plan.
docs/internal/plan-events-as-source-of-truth.md 1 Implementation plan/summary rather than current contract reference.
docs/internal/slow-test-opportunities-2026-04-07.md 1 Dated measurement dataset and implementation-status record.

This exclusion does not include docs/public/changelog/**: the changelog is a live, complete Mintlify publication surface and is mapped as its own component.

Generated Graphviz renderings — 44 files

Glob/path Unique count Evidence
docs/internal/demo/*.svg 11 Every file contains Generated by graphviz; each has a same-stem .fabro source.
docs/internal/demo/*.png 11 Same-stem raster renderings were introduced alongside the .fabro and generated SVG files; their pixel dimensions match the SVG point dimensions at Graphviz's 96-DPI raster scale.
docs/public/images/*-workflow.svg 9 Every matching tracked file contains Generated by graphviz.
docs/public/images/tutorial-*.svg 10 Every matching tracked file contains Generated by graphviz; one file overlaps the previous glob.
docs/public/images/brave-search-research.svg 1 Contains Generated by graphviz.
docs/public/images/how-fabro-works.svg 1 Contains Generated by graphviz.
docs/public/images/nlspec-conformance.svg 1 Contains Generated by graphviz.
docs/public/images/plan-implement-readme.svg 1 Contains Generated by graphviz.

The public SVG rows resolve to 22 unique files because tutorial-sub-workflow.svg matches both broad globs. Curated UI screenshots and hand-authored SVG illustrations remain assigned to public-documentation; docs/internal/updating-web-screenshots.md establishes their manual capture and verification workflow.

The fenced regions in docs/public/reference/cli.mdx and docs/public/reference/user-configuration.mdx are generated, but the files are mixed authored/generated documents. Cartography operates at file granularity, so both whole files stay assigned to public-documentation.

Vendored third-party legal text — 1 file

  • Glob: docs/internal/licenses/graphviz-14.1.5-LICENSE
  • Count: 1.
  • Evidence: the filename pins Graphviz 14.1.5, the contents are the verbatim Eclipse Public License 2.0 plus secondary-license text, and the introducing commit is chore: add vendored Graphviz license to docs-internal/licenses.

Unmapped files

  • Glob: docs/internal/assets/**
  • Count: 15.
  • These form a coherent collection of logos, palette mockups, headers, and HTML/PNG social-card pairs, but no tracked file consumes these exact paths at the assessed revision.
  • docs/internal/updating-web-screenshots.md identifies docs/public/logo/dark.svg and docs/public/logo/light.svg, not the internal assets, as the source-of-truth logos.
  • The collection has no manifest, status marker, or documented update workflow establishing whether it is maintained brand source, derived output, or historical design collateral. It should remain unmapped until that ownership is confirmed.

Coverage

Disposition Count
Assigned to proposed documentation components 268
Cross-scope assignment (install.md to marketing site) 1
Assigned total 269
Excluded historical records 159
Excluded generated renderings 44
Excluded vendored license 1
Excluded total 204
Unmapped internal brand collateral 15
Scoped relevant total 488

269 + 204 + 15 = 488; every scoped tracked file is assigned, excluded, or explicitly unmapped.

Open questions

  1. Are the 15 files under docs/internal/assets/** maintained brand sources, or intentionally retained historical collateral? A component should be added only if an owner/update workflow confirms the former.
  2. Should the parent map keep docs/internal/fabro-event-schema-v2-concrete-shape.md in active engineering guidance, as proposed here based on Status: implemented and recent updates, or treat it as an implemented design record now that Rust event types and events.md carry the live contract?
  3. Confirm the final marketing component ID that will claim the install.md symlink together with apps/marketing/public/install.md.