From 7bd02a8017f0e53e2a37ff94b1a8d2e65bad04eb Mon Sep 17 00:00:00 2001 From: Graham Barber Date: Mon, 17 Aug 2026 13:32:44 -0700 Subject: [PATCH] docs(openspec): archive docs-site Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01PWXFcuaRLZycYVAF7senMK --- .../2026-08-17-docs-site}/.openspec.yaml | 0 .../2026-08-17-docs-site}/design.md | 0 .../2026-08-17-docs-site}/proposal.md | 0 .../specs/documentation/spec.md | 0 .../2026-08-17-docs-site}/tasks.md | 0 openspec/specs/documentation/spec.md | 50 +++++++++++++++++++ 6 files changed, 50 insertions(+) rename openspec/changes/{docs-site => archive/2026-08-17-docs-site}/.openspec.yaml (100%) rename openspec/changes/{docs-site => archive/2026-08-17-docs-site}/design.md (100%) rename openspec/changes/{docs-site => archive/2026-08-17-docs-site}/proposal.md (100%) rename openspec/changes/{docs-site => archive/2026-08-17-docs-site}/specs/documentation/spec.md (100%) rename openspec/changes/{docs-site => archive/2026-08-17-docs-site}/tasks.md (100%) create mode 100644 openspec/specs/documentation/spec.md diff --git a/openspec/changes/docs-site/.openspec.yaml b/openspec/changes/archive/2026-08-17-docs-site/.openspec.yaml similarity index 100% rename from openspec/changes/docs-site/.openspec.yaml rename to openspec/changes/archive/2026-08-17-docs-site/.openspec.yaml diff --git a/openspec/changes/docs-site/design.md b/openspec/changes/archive/2026-08-17-docs-site/design.md similarity index 100% rename from openspec/changes/docs-site/design.md rename to openspec/changes/archive/2026-08-17-docs-site/design.md diff --git a/openspec/changes/docs-site/proposal.md b/openspec/changes/archive/2026-08-17-docs-site/proposal.md similarity index 100% rename from openspec/changes/docs-site/proposal.md rename to openspec/changes/archive/2026-08-17-docs-site/proposal.md diff --git a/openspec/changes/docs-site/specs/documentation/spec.md b/openspec/changes/archive/2026-08-17-docs-site/specs/documentation/spec.md similarity index 100% rename from openspec/changes/docs-site/specs/documentation/spec.md rename to openspec/changes/archive/2026-08-17-docs-site/specs/documentation/spec.md diff --git a/openspec/changes/docs-site/tasks.md b/openspec/changes/archive/2026-08-17-docs-site/tasks.md similarity index 100% rename from openspec/changes/docs-site/tasks.md rename to openspec/changes/archive/2026-08-17-docs-site/tasks.md diff --git a/openspec/specs/documentation/spec.md b/openspec/specs/documentation/spec.md new file mode 100644 index 0000000..f605254 --- /dev/null +++ b/openspec/specs/documentation/spec.md @@ -0,0 +1,50 @@ +# documentation Specification + +## Purpose +TBD - created by archiving change docs-site. Update Purpose after archive. +## Requirements +### Requirement: The docs surface + +The web frontend SHALL serve a documentation section at `/docs`: an index and five pages — Start here, Install, How dist.town thinks, The front door, CLI reference — rendered in the site's prose voice at measure. Root segments without a dot can never be publishers (handles are domains, DIDs carry `did:`), so the space is grammar-safe without reservations. + +#### Scenario: Docs are reachable and complete + +- **WHEN** a visitor opens `/docs` +- **THEN** the index lists all five pages with descriptions, and each page renders server-side under the site chrome + +### Requirement: The quickstart completes + +The Start here page SHALL take a publisher with a fresh ATProto account from nothing to a published release with notes — install, login, publish — using only commands that exist, in their current flag shapes. + +#### Scenario: A stranger follows the arc + +- **WHEN** a publisher with no prior dist.town contact follows Start here top to bottom +- **THEN** every command runs as written and ends with a resolving project page and `@latest` address + +### Requirement: The front-door reference is exact + +The front door page SHALL document the machine surface as implemented: the URL grammar (publisher forms, nested project paths, `@` selectors, `~` facets), artifact 302s, `SHA256SUMS` and `.sha256` endpoints, the `X-Dist-Status` header, checksums derived from the signed record, and yank semantics (explicit version serves with status; pointer to a yanked release refuses). + +#### Scenario: Reference matches server + +- **WHEN** any URL shape or header named on the page is exercised against the running service +- **THEN** the behavior matches the page + +### Requirement: Install carries verification + +The Install page SHALL include verifying the downloaded CLI via the checksum endpoints — the first touch teaches the trust model. + +#### Scenario: Fresh install is verifiable + +- **WHEN** a visitor follows the install instructions +- **THEN** they have run a checksum verification against `SHA256SUMS` before first use + +### Requirement: A contact path exists + +Docs pages SHALL carry a contact line for questions and reports — the interim intake until `moderation-pipeline` lands structured reporting. + +#### Scenario: A visitor can reach the operator + +- **WHEN** a visitor needs to report content or ask a question from any docs page +- **THEN** a working contact link is present in the page chrome + -- 2.51.2