1 file changed
+139
.agents/skills/smbcloud-docs-release/SKILL.md
new
+139
@@ -0,0 +1,139 @@
1
+---
2
+name: smbcloud-docs-release
3
+description: Use when building, generating, or releasing the smbCloud documentation site (`website/`, Nextra + Next.js) — the developer-docs generation pipeline that reads the sibling `docs/` tree, the `nextjs-ssr` deploy via `smb deploy`, and the public-repo content boundary.
4
+---
5
+
6
+# smbCloud Docs Release
7
+
8
+Use this skill when work touches the documentation site that lives at `website/`
9
+in this repo (Nextra 4 on Next.js 16, indexed with Pagefind).
10
+
11
+Applies to:
12
+
13
+- the developer-docs generation pipeline (`website/scripts/generate-developer-docs.mjs`)
14
+- editing or adding pages under `website/content/`
15
+- the source docs under `docs/` (the single source of truth for `/developer`)
16
+- deploying the site with `smb deploy` (`kind = "nextjs-ssr"`)
17
+- the public-repo content boundary for anything published to the docs site
18
+
19
+For the mechanics of the `nextjs-ssr` deploy path itself (standalone build,
20
+rsync layout, PM2, nginx), read the `smbcloud-deploy-nextjs` skill — this skill
21
+only covers what is docs-specific.
22
+
23
+## Layout
24
+
25
+```
26
+smbcloud-cli/
27
+├── docs/ # plain Markdown — the source of truth for /developer pages
28
+└── website/ # the Nextra site (Next.js 16, src-less app/ layout)
29
+ ├── content/ # MDX pages: about, auth, deploy, gresiq, mail, developer/
30
+ │ └── developer/ # index.mdx hand-written; cli/ + contributing/ generated
31
+ ├── scripts/generate-developer-docs.mjs
32
+ └── next.config.mjs # output: 'standalone' (required by nextjs-ssr deploy)
33
+```
34
+
35
+`docs/` sits next to `website/` at the repo root. The site reads it **in place**
36
+— no git clone, no network fetch.
37
+
38
+## Developer-docs generation
39
+
40
+`/developer` CLI and contributing pages are **generated**, not hand-edited.
41
+`website/scripts/generate-developer-docs.mjs` reads files from `../docs`, wraps
42
+each with an "auto-generated, edit at source" callout linking back to the
43
+`docs/` file on GitHub, and writes `.mdx` plus `_meta.js` into
44
+`content/developer/{cli,contributing}/`.
45
+
46
+Key rules:
47
+
48
+- **`docs/` is the single source of truth.** Edit the Markdown in `docs/`, never
49
+ the generated `.mdx` under `content/developer/cli|contributing/`.
50
+- **Generated files are gitignored.** See `website/.gitignore` — the generated
51
+ `.mdx` and `_meta.js` are excluded so they never drift in git. Do not commit them.
52
+- **Hand-written index pages are never touched.** `content/developer/index.mdx`
53
+ (and any section `index.mdx`) use `asIndexPage` frontmatter and are not in the
54
+ manifest. The script only writes the files listed in `MANIFEST` and the
55
+ generated `_meta.js`.
56
+- **Adding a page:** add the `docs/*.md` source, then add an entry to `MANIFEST`
57
+ in the generator (`src`, `slug`, `title`) under `cli` or `contributing`. Then
58
+ add the new generated path to `website/.gitignore`.
59
+- **Excluded sources:** not every file in `docs/` is published — e.g. scratch
60
+ notes are intentionally left out of `MANIFEST`. Only manifest entries ship.
61
+
62
+The generator runs automatically:
63
+
64
+```jsonc
65
+"predev": "pnpm docs:generate", // before `next` dev
66
+"prebuild": "pnpm docs:generate", // before `next build`
67
+"docs:generate": "node scripts/generate-developer-docs.mjs"
68
+```
69
+
70
+You rarely run it by hand; `pnpm dev` and `pnpm build` regenerate first. Run
71
+`pnpm docs:generate` manually only to inspect the output.
72
+
73
+## Build and local preview
74
+
75
+From `website/`:
76
+
77
+```sh
78
+pnpm install
79
+pnpm dev # regenerates developer docs, then `next` dev
80
+pnpm build # regenerates, `next build`, then Pagefind indexes the output
81
+```
82
+
83
+`postbuild` runs Pagefind over `.next/server/app` and writes the search index to
84
+`public/_pagefind`. A green `pnpm build` should report the expected page count
85
+from Pagefind — a drop usually means a generated page failed to render or a
86
+manifest entry was dropped.
87
+
88
+`next.config.mjs` sets `output: 'standalone'`. Do not remove it — the
89
+`nextjs-ssr` deploy path rsyncs `.next/standalone/` and aborts without it.
90
+
91
+## Releasing (deploy)
92
+
93
+The site ships through the CLI's `nextjs-ssr` deploy path, **not** through the
94
+crate/npm/PyPI release flow (that is `smbcloud-cli-release`, a different thing).
95
+
96
+```sh
97
+smb deploy --project <docs-project-name>
98
+```
99
+
100
+Because this site is `kind = "nextjs-ssr"`, `smb deploy`:
101
+
102
+1. runs the build locally (which regenerates the developer docs via `prebuild`),
103
+2. rsyncs `.next/standalone/` + `.next/static/` + `public/` to the server,
104
+3. restarts the app under PM2 over SSH.
105
+
106
+The operational deploy fields (port, remote path, PM2 name, workspace/app IDs)
107
+are **server-side config**, not in the committed `.smb/config.toml` — see the
108
+public-repo boundary below. `smb deploy` fetches them from the API and merges
109
+over the minimal local config. See `smbcloud-deploy-nextjs` for the full deploy
110
+mechanics and `smbcloud-deploy-monorepo` if deploying as a named sub-project.
111
+
112
+## Public-repo content boundary
113
+
114
+**This repo is public**, so everything in `docs/` and `website/content/` is
115
+world-readable and permanent. Read the root `CLAUDE.md` boundary section before
116
+publishing. In docs content specifically, keep out:
117
+
118
+- real customer/app domains, server hostnames/IPs, internal ports, PM2 names
119
+- account/user IDs, workspace/project IDs, `frontend_app_id`/`deploy_repo_id`
120
+- account-scoped SSH key names (`id_<n>@smbcloud`) and the production port registry
121
+- secrets, tokens, `.env` values, real auth/CORS origins
122
+- named incidents or examples tied to a real tenant/customer
123
+
124
+Write generically with placeholders (`example.com`, `<app>`, `<port>`, `<n>`).
125
+The base API host (`api.smbcloud.xyz`) is already in the CLI source, so it is not
126
+a new leak; the items above are. Operational deploy config stays off-disk
127
+(server-side); the committed `.smb/config.toml` is gitignored for the same reason.
128
+
129
+## Common mistakes
130
+
131
+- editing a generated `content/developer/{cli,contributing}/*.mdx` instead of the
132
+ `docs/*.md` source — your change is overwritten on the next build
133
+- committing generated developer docs (they are gitignored on purpose)
134
+- adding a `docs/` page but forgetting the `MANIFEST` entry (it never ships) or
135
+ the `website/.gitignore` line (it gets committed)
136
+- removing `output: 'standalone'` from `next.config.mjs` — breaks the deploy
137
+- writing real domains, ports, IDs, or secrets into published docs content
138
+- confusing docs release (`smb deploy` nextjs-ssr) with the CLI crate/npm/PyPI
139
+ release flow (`smbcloud-cli-release`)