claude/smbcloud-github-app-k9641p
claude/smbcloud-github-app-k9641p
development
feature/apps
feature/build-release
feature/ci-docs
feature/ci-ruby-gems
feature/cicd
feature/completion
feature/dist-nuget
feature/fix-ci-sdk-pypi-rubygem
feature/fix-clippy-on-stable-channel
feature/fix-deployment-script
feature/github-email
feature/gresiq-v1
feature/project-new-structure
feature/rsync-deploy
feature/ruby-runner
feature/sdk-npm
feature/sdk-workflows
feature/smbcloud-cli-release-npm
feature/smbcloud-deploy
feature/wasm
main
release/v0.7.4
| 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`) |