docs: move documentation under /docs with standard section names

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -12,7 +12,7 @@ body:
 
         [`docs/product.md`](https://github.com/labstack/onebox/blob/main/docs/product.md)
         records the direction, and
-        [`/status/capabilities`](https://onebox.run/status/capabilities) records
+        [`/docs/reference/capabilities`](https://onebox.run/docs/reference/capabilities) records
         what the binary does today versus what the schema merely accepts.
 
   - type: textarea

.github/PULL_REQUEST_TEMPLATE.md

@@ -18,7 +18,7 @@ output you compared, or the invariant it preserves.
 <!--
 Does this change what Onebox will do to a running production system, or move
 something between "the schema accepts it" and "the binary does it"? If so, say
-so here and note the corresponding /status/capabilities update. Write "None" if
+so here and note the corresponding /docs/reference/capabilities update. Write "None" if
 neither applies.
 -->
 

.gitignore

@@ -27,7 +27,7 @@
 .playwright-mcp/
 
 # Documentation site build output and dependencies. The generated reference
-# pages under site/src/content/docs/reference/ are NOT ignored: they are
+# pages under site/src/content/docs/docs/reference/ are NOT ignored: they are
 # committed so a reader of the repository sees the same reference a reader of
 # the site does, and so `just docs-generate-check` can prove they are current.
 /site/node_modules/

CONTRIBUTING.md

@@ -27,7 +27,7 @@ product decision, not a code review question, and it is far cheaper to settle
 before the code exists.
 
 [`docs/product.md`](docs/product.md) records the direction, and
-`/status/capabilities` records what the binary does today versus what the schema
+`/docs/reference/capabilities` records what the binary does today versus what the schema
 merely accepts. A change that moves something between those two states should
 say so in its description.
 
@@ -73,7 +73,7 @@ just e2e
 ## Generated documentation
 
 The field reference, CLI reference, and error code pages under
-`site/src/content/docs/reference/` are **generated from the binary** by
+`site/src/content/docs/docs/reference/` are **generated from the binary** by
 `cmd/ob-docgen`. Do not hand-edit them; they are committed so that a reader of
 the repository sees the same reference a reader of the website does.
 

README.md

@@ -11,7 +11,7 @@ server.
 
 [![CI](https://img.shields.io/github/actions/workflow/status/labstack/onebox/ci.yml?branch=main&label=ci&color=4f9a3c&labelColor=22291f)](https://github.com/labstack/onebox/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/labstack/onebox?label=release&color=4f9a3c&labelColor=22291f)](https://github.com/labstack/onebox/releases) [![Licence](https://img.shields.io/badge/licence-Apache--2.0-4f9a3c?labelColor=22291f)](LICENSE)
 
-[Documentation](https://onebox.run) · [Install](https://onebox.run/start/install) · [First deploy](https://onebox.run/start/first-deploy) · [Capabilities](https://onebox.run/status/capabilities) · [Releases](https://github.com/labstack/onebox/releases)
+[Documentation](https://onebox.run/docs) · [Install](https://onebox.run/docs/get-started/install) · [First deploy](https://onebox.run/docs/get-started/first-deploy) · [Capabilities](https://onebox.run/docs/reference/capabilities) · [Releases](https://github.com/labstack/onebox/releases)
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/media/deploy-dark.svg">
@@ -60,7 +60,7 @@ owns the generated application runtime inside that boundary.
 ### 1. Install the CLI
 
 Homebrew, Scoop, release archives, and Debian/RPM packages are available. The
-[installation guide](https://onebox.run/start/install) includes checksum
+[installation guide](https://onebox.run/docs/get-started/install) includes checksum
 verification and source builds.
 
 ```sh
@@ -112,7 +112,7 @@ expires after 15 minutes; drift or a changed local payload requires a new one.
 
 Approval is a short-lived, digest-bound local confirmation. It is
 tamper-evident ceremony, not authenticated identity or an independently issued
-capability. See [Your first deploy](https://onebox.run/start/first-deploy) for
+capability. See [Your first deploy](https://onebox.run/docs/get-started/first-deploy) for
 the complete walkthrough and expected output.
 
 ## Refusing is part of the contract
@@ -127,8 +127,8 @@ Onebox refuses configurations it cannot operate safely, including:
 
 There is no generic `--force`. Each exceptional path grants one named
 capability, such as breaking a stale lock or accepting a destructive volume
-change. [What Onebox refuses](https://onebox.run/explanation/what-onebox-refuses)
-and [the safety envelope](https://onebox.run/explanation/safety-envelope) give
+change. [What Onebox refuses](https://onebox.run/docs/concepts/what-onebox-refuses)
+and [the safety envelope](https://onebox.run/docs/concepts/safety-envelope) give
 the full rules.
 
 ## Boundaries that matter
@@ -143,7 +143,7 @@ the full rules.
 - **MongoDB is standalone.** Applications requiring change streams or
   multi-document transactions need a replica set, which Onebox does not manage.
 
-[Shipped vs proposed](https://onebox.run/status/capabilities) is the complete
+[Shipped vs proposed](https://onebox.run/docs/reference/capabilities) is the complete
 account of what the binary executes today and what remains direction.
 
 ## How it compares
@@ -172,28 +172,28 @@ are typed: branch on the code, never the sentence.
 There is deliberately no MCP mutation surface. Point an agent at `ob` the way
 you would point it at `gh`; every lifecycle decision still passes through the
 same canonical service and safety checks. See the
-[structured-output policies](https://onebox.run/reference/policies#structured-output-contracts).
+[structured-output policies](https://onebox.run/docs/reference/policies#structured-output-contracts).
 
 ## Documentation
 
 Every page on **[onebox.run](https://onebox.run)** is also available as clean
 Markdown at `<path>.md`; [llms.txt](https://onebox.run/llms.txt) maps the site
 for agents.
 
-- **Start:** [installation](https://onebox.run/start/install) and
-  [your first deploy](https://onebox.run/start/first-deploy)
-- **Operate:** [databases](https://onebox.run/guides/add-a-database),
-  [backups](https://onebox.run/guides/back-up-a-database),
-  [migrations](https://onebox.run/guides/run-migrations),
-  [secrets](https://onebox.run/guides/handle-secrets), and
-  [rollback](https://onebox.run/guides/roll-back)
-- **Reference:** [project file](https://onebox.run/reference/project-file),
-  [CLI](https://onebox.run/reference/cli),
-  [errors](https://onebox.run/reference/errors), and
-  [policies](https://onebox.run/reference/policies)
-- **Understand:** [ownership boundary](https://onebox.run/explanation/ownership-boundary),
-  [evidence, not declaration](https://onebox.run/explanation/evidence-not-declaration),
-  and [generated Compose](https://onebox.run/explanation/generated-compose)
+- **Start:** [installation](https://onebox.run/docs/get-started/install) and
+  [your first deploy](https://onebox.run/docs/get-started/first-deploy)
+- **Operate:** [databases](https://onebox.run/docs/guides/databases),
+  [backups](https://onebox.run/docs/guides/backups),
+  [migrations](https://onebox.run/docs/guides/migrations),
+  [secrets](https://onebox.run/docs/guides/secrets), and
+  [rollback](https://onebox.run/docs/guides/rollback)
+- **Reference:** [project file](https://onebox.run/docs/reference/project-file),
+  [CLI](https://onebox.run/docs/reference/cli),
+  [errors](https://onebox.run/docs/reference/errors), and
+  [policies](https://onebox.run/docs/reference/policies)
+- **Understand:** [ownership boundary](https://onebox.run/docs/concepts/ownership-boundary),
+  [evidence, not declaration](https://onebox.run/docs/concepts/evidence-not-declaration),
+  and [generated Compose](https://onebox.run/docs/concepts/generated-compose)
 
 The field, CLI, and error references are generated from the binary by
 `cmd/ob-docgen`, so documentation cannot silently drift from the accepted

cmd/ob-docgen/main.go

@@ -7,7 +7,7 @@
 // contract that disagrees with the loader is worse than none — it teaches the
 // author something untrue and they learn to ignore it.
 //
-// So this program is the only writer of `site/src/content/docs/reference/`
+// So this program is the only writer of `site/src/content/docs/docs/reference/`
 // — the field pages, `drivers.mdx`, `errors.mdx` and `cli.mdx` — and of the
 // schema published below `site/public/schemas/application/v1alpha2/`. Those pages carry
 // a generated marker,
@@ -45,7 +45,7 @@ func main() {
 		obBin  string
 		check  bool
 	)
-	flag.StringVar(&out, "out", "site/src/content/docs/reference", "directory to write generated reference pages into")
+	flag.StringVar(&out, "out", "site/src/content/docs/docs/reference", "directory to write generated reference pages into")
 	flag.StringVar(&public, "public", "site/public", "directory to publish machine-readable artifacts into")
 	flag.StringVar(&obBin, "ob", "", "path to a built ob binary, for the CLI reference (default: look on PATH)")
 	flag.BoolVar(&check, "check", false, "fail if the files on disk differ from what would be generated")
@@ -1009,14 +1009,14 @@ func renderDriverPage() string {
 	fmt.Fprintln(&buf, "rather than replacing the container and leaving the data intact and unreachable.")
 	fmt.Fprintln(&buf)
 	fmt.Fprintln(&buf, "For `postgres`, declaring `backup` changes this — see")
-	fmt.Fprintln(&buf, "[Shipped vs proposed](/status/capabilities).")
+	fmt.Fprintln(&buf, "[Shipped vs proposed](/docs/reference/capabilities).")
 	fmt.Fprintln(&buf, ":::")
 	fmt.Fprintln(&buf)
 
 	fmt.Fprintln(&buf, "## Anything else")
 	fmt.Fprintln(&buf)
 	fmt.Fprintln(&buf, "Run it as a `daemon` workload and you own it: the image, the credential, the")
-	fmt.Fprintln(&buf, "volumes, the backup. See [Add a database](/guides/add-a-database) for the")
+	fmt.Fprintln(&buf, "volumes, the backup. See [Add a database](/docs/guides/databases) for the")
 	fmt.Fprintln(&buf, "comparison.")
 
 	return buf.String()

cmd/ob-docgen/main_test.go

@@ -26,7 +26,7 @@ func TestCLIReferenceMatchesBinary(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	path := filepath.Join("..", "..", "site", "src", "content", "docs", "reference", "cli.mdx")
+	path := filepath.Join("..", "..", "site", "src", "content", "docs", "docs", "reference", "cli.mdx")
 	committed, err := os.ReadFile(path)
 	if err != nil {
 		t.Fatal(err)
@@ -360,7 +360,7 @@ func TestCommittedPagesMatchTheGenerator(t *testing.T) {
 	want["errors.mdx"] = renderErrorPage()
 	want["drivers.mdx"] = renderDriverPage()
 
-	root := filepath.Join("..", "..", "site", "src", "content", "docs", "reference")
+	root := filepath.Join("..", "..", "site", "src", "content", "docs", "docs", "reference")
 	for name, body := range want {
 		onDisk, err := os.ReadFile(filepath.Join(root, filepath.FromSlash(name)))
 		if err != nil {

cmd/ob/docs_test.go

@@ -11,9 +11,9 @@ import (
 	"github.com/spf13/pflag"
 )
 
-const cliReferencePage = "site/src/content/docs/reference/cli.mdx"
+const cliReferencePage = "site/src/content/docs/docs/reference/cli.mdx"
 
-const policiesPage = "site/src/content/docs/reference/policies.mdx"
+const policiesPage = "site/src/content/docs/docs/reference/policies.mdx"
 
 // readDocsPage reads a documentation page from the site. The remediation hint
 // belongs at the call site: only some of these pages are generated, and telling

context7.json

@@ -3,13 +3,13 @@
   "projectTitle": "Onebox",
   "description": "Plan-before-apply deploys for one application on one Linux server. Zero downtime, no agent on the host.",
   "branch": "main",
-  "folders": ["site/src/content/docs", "README.md"],
+  "folders": ["site/src/content/docs/docs", "README.md"],
   "excludeFolders": ["docs/plans", "docs/superpowers", "docs/media"],
   "rules": [
     "The CLI is `ob`. The application is declared in `ob.yml` (or `ob.yaml`), from which Onebox derives the Compose runtime, stable names, routing, supporting services, and release operations.",
     "Nothing runs against production until a plan is approved: `ob plan` prints a digest-bound diff of config, images, host state, rendered Compose, payloads, and the operation graph; `ob deploy` applies it.",
     "Onebox connects over SSH with host-key verification. There is no deployment agent to install on the target host.",
     "Onebox targets a single Linux server running a single application. Do not present it as a multi-node orchestrator or a Kubernetes alternative for clusters.",
-    "Documentation is at https://onebox.run. The Go module path is `github.com/labstack/onebox`."
+    "Documentation is at https://onebox.run/docs. The Go module path is `github.com/labstack/onebox`."
   ]
 }

docs/README.md

@@ -15,16 +15,16 @@ the repository rather than to a reader.
 
 | Was | Now |
 |---|---|
-| `docs/cli.md` | `/reference/cli` — generated from the binary by `cmd/ob-docgen` |
-| `docs/schema-v1.md` | `/reference/project-file` and the generated field pages under `/reference/fields/` |
-| The authority map that used to live here | `/status/capabilities` — every capability marked shipped, schema-only, or intent-only |
+| `docs/cli.md` | `/docs/reference/cli` — generated from the binary by `cmd/ob-docgen` |
+| `docs/schema-v1.md` | `/docs/reference/project-file` and the generated field pages under `/docs/reference/fields/` |
+| The authority map that used to live here | `/docs/reference/capabilities` — every capability marked shipped, schema-only, or intent-only |
 
 ## Which documents are authoritative
 
 Documentation says what is true **today**. Direction lives in
 [`product.md`](product.md), and it is not presented as a capability. What the
 binary actually does is the generated reference under
-`site/src/content/docs/reference/`, produced by `cmd/ob-docgen` and checked
+`site/src/content/docs/docs/reference/`, produced by `cmd/ob-docgen` and checked
 against the binary by `just docs-generate-check`, so it cannot describe
 something the loader does not accept.
 

docs/product.md

@@ -4,7 +4,7 @@
 >
 > Not an implementation contract. See the [documentation authority
 > map](README.md) for what is shipped, and the
-> [capabilities page](../site/src/content/docs/status/capabilities.mdx) for what
+> [capabilities page](../site/src/content/docs/docs/reference/capabilities.mdx) for what
 > the binary does today versus what the schema merely accepts.
 
 ## Product statement
@@ -175,7 +175,7 @@ declaration is never presented as proof that protection is running.
 
 This tier is direction, not current behaviour. The canonical facts carry the
 field and validate it, but nothing assigns a tier yet, and no surface reports
-one — see [Shipped vs proposed](../site/src/content/docs/status/capabilities.mdx).
+one — see [Shipped vs proposed](../site/src/content/docs/docs/reference/capabilities.mdx).
 
 ## Delivery discipline
 

internal/app/jsonschema_test.go

@@ -341,8 +341,8 @@ func TestPublishedSchemaURLIsUsedByTheHumanGuide(t *testing.T) {
 		t.Fatalf("schema identity = %q", SchemaID)
 	}
 	guides := []string{
-		"site/src/content/docs/start/reading-it-back.mdx",
-		"site/src/content/docs/reference/project-file.mdx",
+		"site/src/content/docs/docs/get-started/reading-it-back.mdx",
+		"site/src/content/docs/docs/reference/project-file.mdx",
 	}
 	for _, guide := range guides {
 		body, err := os.ReadFile(filepath.Join("..", "..", filepath.FromSlash(guide)))

internal/app/prerequisites.go

@@ -34,7 +34,7 @@ const (
 // Docker" is the wrong advice for the common case where Docker is installed and
 // the deploy account simply cannot reach its socket.
 const (
-	prerequisiteDocs = "https://onebox.run/start/install"
+	prerequisiteDocs = "https://onebox.run/docs/get-started/install"
 
 	runtimeAbsentRemedy      = "install Docker Engine, the Compose plugin and Buildx on the server (" + prerequisiteDocs + "), then rerun ob preflight"
 	runtimeDeniedRemedy      = "add the deploy account to the docker group on the server and reconnect so the new membership applies, then rerun ob preflight"