Documentation site status and migration map ​

The static VitePress site is published at https://constructorfleet.github.io/SketchForge-3D/. The repository remains the source for maintained prose, examples, and generated references. On pull requests, docs CI generates references before verification and site build, then uploads the generated outputs. A trusted default-branch follow-up validates the artifact and PR before committing only allowlisted updates to same-repository PR branches. A separate trusted workflow checks the exact resulting SHA in read-only jobs and records the required contexts without checking out PR code in the check-writing job. Fork PRs use the generated artifact fallback because their branches cannot be pushed. Successful docs builds on main also upload their outputs; a trusted writer opens or refreshes a bot repair PR if tracked outputs differ. Main remains stale only until that repair PR is merged, and CI regenerates before validation so stale tracked output alone does not fail the docs check.

Delivered site capabilities ​

  • Project-path routing, local search, navigation, recursive source includes, local-link checks, a local preview command, and GitHub Pages deployment.
  • Compatibility pages and redirects preserve the repository's public documentation paths. See the historical inbound-link inventory for the repository-controlled paths and their destinations.
  • Source provenance is rendered into built pages: package version, repository revision, and source links point to the revision represented by the build.
  • The built-site browser checks cover navigation, visible focus, landmarks, headings, search, responsive behavior, accessible names, contrast, alt text, reduced motion, and 320px reflow. A separate browser check exercises the editor quick-start. The docs workflow installs its pinned browser runtime.
  • External-link availability is reported in a separate advisory job. Remote failures do not block the deterministic local docs check or site build.

Current reference coverage ​

  • TypeScript, Python, and engine references are generated into .docs-site/docs/reference/ from package declarations and public exports. Their rendered pages are validated as part of the Pages artifact.
  • Seven generators write tracked output for repository browsing: docs/PUBLISHING_CLIENTS.md, docs/SHAPE_REQUEST_REFERENCE.md, docs/CLI_REFERENCE.md, docs/OPERATOR_CONFIGURATION.md, docs/SKF_FORMAT_REFERENCE.md, docs/mcp/TOOLS_REFERENCE.md, and docs/openapi-v1.json. The OpenAPI JSON is linked directly from docs/REST_API.md. PR docs CI runs docs:generate before generated-output verification and site build, then uploads generated output. A trusted workflow_run handler treats that artifact as untrusted input, verifies its manifest and source PR, and writes only allowlisted generated paths. It commits changed outputs to same-repository PR branches and dispatches a default-branch verifier for the exact resulting SHA. Fork PRs use the artifact fallback. Successful main docs runs create or refresh one bot repair PR when generated tracked output differs; protected main is never written directly by the workflow. The TypeScript, Python, and engine references remain generated in .docs-site/docs/reference/ for the Pages artifact, not tracked source files.
  • Package guides include registry-facing README files, and package examples run against a local API. Python package references and examples are checked with mypy and integration tests. The REST guide's plate-and-holes walkthrough and the import-inspect-export guide's STL workflow are included from docs/examples/rest-hole-plate.mjs and docs/examples/rest-import-inspect-export.mjs, then run against temporary local project storage. Tests verify the boolean cut or STL import → property inspection → export, and project cleanup. The MCP example is checked against the server's current advertised tool schemas.
  • Browser acceptance covers the editor quick-start and the edit-and-export guide's create, edit, save, reload, and export workflow. The face-drafting guide covers one inspector case (face 1, local +Z, -5°) with screenshot evidence. The sketch-constraints guide covers Parallel and Perpendicular workflows with screenshots. The Perpendicular case distorts a rectangle corner, applies the relation to adjoining segments, and verifies a 90° result. These cases do not establish broad face-drafting, sketch-constraint, or task-workflow coverage; broader task-oriented guides and corresponding workflow checks remain incomplete.

REST API coverage ​

apps/web/src/lib/apiV1OperationContract.ts registers all 32 public route operations, and route tests check parity between the registry and handlers. 28 operations have runtime-backed request and response contracts and appear in generated OpenAPI. The four OPTIONS preflights are intentionally omitted; all resource route coverage is complete. POST /mirrors validates normalized IDs, axis selection, response shape, and reachable errors at the route boundary. POST /patterns validates normalized IDs, defaults, count limits, finite numeric options, its 201 shape-summary response, and reachable errors. POST /explode validates trimmed project and shape IDs, STEP assembly summaries, revision, and reachable errors. POST /imports documents base64 JSON and multipart upload bodies, validates the stable shape/triangle-count/revision response, and checks reachable JSON errors at the route boundary. POST /exports documents its request constraints, JSON/base64 result, conditional raw artifact response and metadata header, and reachable errors.

PATCH /api/v1/shapes accepts sketchProfile for a retained sketch sweep, targeted by either its output shape ID or persisted sketchSourceId, and rebuilds the solid while preserving shape and source IDs. Editing a sketch-backed sweep also recomputes retained boolean descendants bottom-up and persists the result atomically. Other downstream operation types remain unsupported. PATCH /shapes is represented in OpenAPI with the faceColors key and hex-color constraints; other engine patch fields, including sketchProfile, remain extensible and are validated by the runtime route. See the REST API guide and the kernel capability inventory.

Durable gaps ​

  • REST contracts and generated operation pages — met for resource operations: all 28 non-OPTIONS resource operations have runtime-backed OpenAPI contracts and generated Pages references with authentication, parameters, request and response schemas, errors, and source links. The four omitted operations are preflight-only OPTIONS handlers. The REST API guide links to the generated index and retains conceptual explanations and runnable workflows.
  • Generated-output automation — implemented with limits: generators run before verification/build, and a trusted artifact-only writer commits allowlisted updates to same-repository PR branches before exact-SHA checks are recorded by a default-branch workflow. Fork PRs use artifact fallback. Successful main docs runs open or refresh a bot repair PR for stale tracked output; main remains stale until that repair PR is merged.
  • Configuration ownership — implemented for the declared supported inventory: the generated operator reference is backed by a registry of supported server/container, desktop, TypeScript/Python client, and local MCP settings. The desktop entry includes SKETCHFORGE_DESKTOP_PORT; the registry links settings to their implementation readers and owning pages, and tests detect unregistered readers within those tracked scopes. It does not treat every environment read as a supported setting: for example, SKETCHFORGE_DESKTOP_DEV_URL is an internal launcher handoff and NODE_PATH is pass-through. Build, test, CI, launcher, pass-through, and other readers outside the declared inventory remain out of scope.
  • Examples and page ownership — partial: all maintained docs/**/*.md pages and staged generated package references have required audience/owner metadata. A separate docs check covers 25 supported-language runnable fences: each must include its exact tracked source with a named test and CI command, or carry a concrete reasoned exemption. Exemptions do not establish execution coverage, and other fence languages and runnable content outside this set are not covered. Changed-source ownership diagnostics cover selected source trees, including REST routes, the REST guide's plate-and-holes fixture, the import-inspect-export guide's workflow fixture, TypeScript client/MCP, engine, Python client, and the package example trees. The mapping is path-based and is not symbol-level or complete repository coverage. The local-project MCP shell command is included from and executed as the same source fixture; package examples and both REST walkthroughs are sourced and tested. The STEP assemblies guide's .skf import and local MCP sketchforge_import_project → sketchforge_explode_step_assembly workflow has browser acceptance in tests/browser/editor-quickstart.test.mjs: it imports tests/fixtures/step/nested-assembly.step through the editor, exports the actual .skf download, passes that exact file through both MCP calls, checks nested groups, exact per-leaf occurrence IDs, and complete ordered root-to-leaf paths, cleans up temporary project files, and captures docs/screenshots/step-assembly-editor-import.png. tests/unit/localMcpEngine.test.ts separately covers the package/MCP path. Other REST request examples remain unexecuted or exempt. The sketch-constraints guide maps the selected editor sources SketchForgeEditor.tsx, SketchWorkspace.tsx, and sketchConstraints.ts; SketchForgeEditor.tsx also maps to the edit-and-export guide. Other editor/UI sources, other examples, and all content sources remain open for ownership diagnostics.
  • Task workflows: the STEP assembly guide's editor import → actual .skf download → local MCP import/explode path now has browser acceptance with screenshot evidence. Expand tested task guides beyond the editor quick-start, edit-and-export, the STEP assembly workflow, one face-drafting case, Parallel and Perpendicular constraint workflows, package examples, and current REST/MCP workflows.
  • Inbound links: local links, compatibility paths, and repository history are inventoried. External backlinks outside repository history cannot be established by this inventory.

See the documentation suite specification for the full objective, source-of-truth rules, implementation phases, and acceptance audit.

Documentation version: 1.30.0 · Repository revision: 1cb9fee8dff4d394684c229dd67a21da539d167f · View source