1.0 Documentation And Public API Plan

Findings To Resolve

The public documentation contains useful material, but release status, directional roadmap, known limitations, contributor internals, and historical hardening detail overlap. Some behavior is repeated across the root README, user guide, roadmap, Known Issues, and contributor guides. The scripts index also has a broken relative link, and the docs drift gate currently interprets generated graph/fuzz/target/ paths as missing documentation references. Contributor documentation also still describes the older four-field EdgeMutation and claims layered neighbors lack stable relationship identity in engine-internals.mdx and traversal-search-paths.mdx. Those statements no longer match the segment and layered-identity implementation.

Information Architecture

Use the following ownership rules:

Information Single source of truth
Installation and supported platforms/PostgreSQL majors User guide installation page
First successful graph workflow Quickstart page
SQL functions, GUCs, options, result shapes, SQLSTATEs Generated/drift-checked API reference
Supported GQL profile Generated capability page backed by conformance metadata
Current limitations and operational consequences Known Issues
Shipped changes and migrations Release notes
Future product direction Roadmap
Internal architecture, scripts, tests, and release process Contributor guide
Active implementation work and measurements todo/ only; never linked as public product docs

README files should introduce and route readers to these sources instead of duplicating detailed contracts.

Cleanup Checklist

  • [x] Rewrite the public roadmap around Current Baseline, 1.0 Focus, and Post-1.0 Direction; remove internal checkpoint language and stale alpha history from the public page.
  • [x] Prune Known Issues to unresolved user-visible limitations. Move resolved migration history to release notes and internal engineering tasks to the 1.0 plan.
  • [x] Reconcile root README.md, README_zh.md, and docs quickstart so commands, supported versions, playground modes, and feature claims agree.
  • [x] Generate API/configuration/diagnostic/GQL capability tables or make their existing hand-maintained sources drift-checked.
  • [x] Add public compatibility, upgrade, rollback, deprecation, backup/restore, resource-limit, and production-readiness guidance.
  • [x] Consolidate architecture descriptions and keep deep implementation detail in contributor docs rather than user pages.
  • [x] Correct stale relationship-identity descriptions in contributor engine and traversal documentation, then add source-linked drift coverage for persisted and layered identity fields.
  • [x] Split the oversized API reference, querying guide, and release-note history into navigable owned sections without changing their public URLs until redirects are available.
  • [x] Fix scripts/scripts.md links and the docs reference checker treatment of generated or intentionally absent paths.
  • [x] Run local-link, external-link, navigation, code-example, API drift, Rust source-map drift, spelling/style, and static rendered-MDX checks. The downstream docs host remains responsible for its application-shell build.
  • [x] Review public tone: describe supported behavior and constraints directly; remove private planning phrases, phase history, and future-tense claims that read as current functionality.
  • [x] Give every maintained example an owner, expected output/checksum, version requirements, and an automated smoke test; delete stale examples.
  • [x] Add a release-note template and a 1.0 migration guide before the first RC.
  • [x] State release maturity consistently: the current line is alpha, and 1.0 becomes production-supported only after the RC checklist is green.
  • [x] Define how README_zh.md is synchronized with the canonical English documentation and prevent unsupported-version or command drift.
  • [x] Verify Rust public API docs, # Errors, # Panics, # Safety, doctests, and generated cargo doc navigation for the supported feature set.

Documentation Release Gate

  • No broken internal links or navigation entries.
  • No undocumented exported SQL function, GUC, option, result contract, stable diagnostic, or supported GQL capability.
  • No public claim exceeds conformance or release evidence.
  • Quickstart and playground instructions pass from a clean packaged install.
  • Known Issues contains every unresolved user-visible P0/P1 limitation and no resolved historical item.
  • Upgrade, rebuild, rollback, backup/restore, and compatibility guidance is complete for PostgreSQL 14-18.