Artifact [2956787a9e]

Artifact 2956787a9e30e5b9191bfad9c03926aa165ad1adbb3c734060c6c8b5c8f69455:

• File docs/site/content/docs/_index.md — part of check-in [f30849a466] at 2026-04-26 14:14:53 on branch trunk — docs: usability improvements from DX audit (#9)

  Implements all seven recommended changes from the docs audit:

  1. SDK pages now show package names in nav. Add scripts/prepend-sdk-frontmatter.sh that prepends '--- title: <pkg> ---' to each gomarkdoc-generated api.md; wired into 'make docs-gen-sdk'. Sidebar previously showed five undifferentiated 'API' entries; now shows cli, db, dst, libfossil, observer/otel.

  2. /examples/ populated with paragraphs + GitHub deep-links for embed-repo-api and wasm. No longer a placeholder pointing back at the repo.

  3. Architecture page gets an inline SVG mirroring the landing-page diagram. Self-contained CSS (uses currentColor + ember accent) so it tracks Hextra's light/dark theme without depending on the landing's CSS scope.

  4. Cross-links added: quickstart -> production + extension-points, migration -> architecture, architecture -> extension-points. Extension Points and Production patterns are now reachable via prose, not just the sidebar.

  5. /docs/ landing expanded from 3 sentences to a 7-line subsection map calling out each page's purpose.

  6. Version indicator in navbar (libfossil v0.4.2). Override layouts/_partials/navbar-title.html mimics Hextra's default and appends a small mono version tag from .Site.Params.version.

  7. New /docs/production/ page covering error handling, context cancellation, telemetry wiring, repo-handle lifetime, and driver selection — the patterns the quickstart's log.Fatal shortcuts gloss over. (user: [email protected], size: 1069) [annotate] [blame] [check-ins using]

---
title: Documentation
cascade:
  type: docs
---

libfossil is a pure-Go library and CLI for reading and writing Fossil SCM repositories. Zero CGo. Static binaries. WASM-ready.

## What you'll find here

- **[Quickstart](./quickstart)** — install the CLI, clone a repo, and read its history from Go in five minutes.
- **[Architecture](./architecture)** — module layout, storage model, driver layer, and the deterministic simulator.
- **[Migration from Fossil](./migration-from-fossil)** — for upstream Fossil users: what's covered, what isn't, and how the CLI shapes differ.
- **[Extension Points](./extension-points)** — observer interfaces for telemetry, custom SQLite drivers, and the `db.DB` abstraction.
- **[Production patterns](./production)** — error handling, context, telemetry wiring beyond the quickstart's `log.Fatal` shortcuts.
- **[Testing](./testing)** — running the suite, the dual-driver matrix, and DST simulation with seeds and BUGGIFY.
- **[SDK reference](./reference/sdk)** — auto-generated Go API reference, one page per package.