Documentation

The published Starlight site is organized around reader journeys (Diátaxis-aligned):

Get started — install, quickstart, tutorial
Use every day — Cypher, construction, analytics, datasets
Understand — architecture Book, use cases, research
Reference — API, compatibility, TCK, changelog
Contribute & operate — development, testing, release, this map
Engineering — contributor lifecycle summaries and ADRs
Community — licensing, security, code of conduct

On disk, public sources live in Guide / Book / Reference / engineering/ plus supporting folders. Product & strategy DocSlime lifecycle docs (PRODUCT, DESIGN, REQUIREMENTS, strategy, experience) live in the private CurateLabs/graphforge-nextjs repository and are not published on GitHub Pages.

The Astro Starlight site (docs-site/) syncs an allowlisted subset of these trees. Sidebar labels follow reader journeys; content paths / URLs stay on the Guide / Book / Reference / engineering layout so existing public links remain stable.

Local docs site

From the repository root (requires Node ≥ 22.12 and the repo pnpm workspace):

pnpm install
pnpm docs:dev          # http://localhost:4321/
pnpm docs:build        # output: docs-site/dist/
pnpm docs:check-links  # after build: zero broken same-site hrefs
pnpm docs:preview      # serve the build output

Makefile shortcuts: make docs-serve, make docs-build, make docs-clean.

Markdown sources stay in docs/; docs-site/scripts/sync-content.mjs copies the allowlist into the Starlight content collection before dev / build.

Published reader map

Journey	Start here
Get started	`guide/installation.md`, `guide/quickstart.md`, `guide/tutorial.md`
Use every day	`guide/overview.md`, Cypher / construction / analytics / `guide/datasets/`
Understand	`book/README.md`, architecture / use cases / research
Reference	`reference/api.md` and siblings
Contribute & operate	`development/contributing.md`, release docs, `releases/roadmap.md`
Engineering	`engineering/` (ADRs under Engineering), `adr/`
Community	`legal/licensing.md`, `community/`

On-disk authoring trees

Guide (basic usage)

Path	Contents
`guide/installation.md`	Install via pip or uv
`guide/quickstart.md`	First graph in minutes
`guide/tutorial.md`	Guided walkthrough
`guide/overview.md`	Everyday workflows index
`guide/cypher-guide.md`	openCypher language guide
`guide/graph-construction.md`	Build graphs with API and Cypher
`guide/analytics-integration.md`	Arrow, pandas, Polars, analyst verbs
`guide/datasets/`	Load real-world networks

Book (research, architecture, deeper usage)

Path	Contents
`book/README.md`	Book map
`book/architecture/`	Pipeline, storage, execution, algorithms, contracts
`book/use-cases/`	Deeper usage narratives
`book/research/`	Present-tense v0.5.0 research notes behind the use cases

Engineering (public contributor lifecycle)

Document	Question it answers
`engineering/ARCHITECTURE.md`	Which concepts, boundaries, and components shape the system?
`engineering/TESTING.md`	How do we prove it before release?
`engineering/PUBLISHING.md`	How do verified artifacts reach users safely?
`engineering/OBSERVABILITY.md`	How do CI/release signals feed learning?
`engineering/adrs/`	ADR index (bodies in `adr/` `0001`–`0014`)

Supporting public trees

Folder	Contents
`index.md`	Site home (reader-journey framed)
`reference/`	API, compatibility, TCK, scale limits
`development/`	Contributor and release process detail
`legal/licensing.md`	Licensing copy
`adr/`	ADR bodies (v0.5.0 keepers `0001`–`0014`)
`releases/roadmap.md`	Public product roadmap

Private product & strategy

Maintainer-oriented DocSlime product planning (market, positioning, requirements, experience journeys) is in graphforge-nextjs docs/ (#2772). Public engineering contributor docs remain in this repository.

Conventions

Keep docs current. When behavior changes, update the doc in the same change.
Link, don’t duplicate. Deep dives stay in book/; product strategy stays private.
Decisions are recorded. Significant choices get ADRs under adr/, indexed from engineering/adrs/.
Site tooling is separate. Starlight config under docs-site/ owns published nav.
Issue closure. Docs and legal issues stay open until manual approval; PRs use Refs #<issue>, not Closes.