@icebreakers/monorepo-templates 3.0.1 → 3.1.0

package/assets/.agents/skills/repoctl/references/commands.md

@@ -1,5 +1,31 @@
 # Commands
 
+## docs plan / docs deploy
+
+```bash
+repo docs plan guide --channel preview --source-sha <full-main-sha> --json
+repo docs plan guide --channel stable --release <completion-record-id> --json
+repo docs plan guide --channel stable --commits <correction-sha> --json
+```
+
+Enable `commands.docs.sites` explicitly. Preview uses the exact latest main source; stable uses a completed main/latest release and the covered packages' publication evidence. `plan` is read-only and does not perform provider credential preflight. Run stable `deploy` with the same inputs through managed `repoctl-docs.yml` / `repoctl-docs-deploy.yml`, with the actual `docs-<site>-<channel>` concurrency group. Keep one deployment owner per channel.
+
+Targets retain `{ deployScript, url? }` or use `{ provider: 'cloudflare-workers', config, workerName, accountId, environment?, url? }`. Do not mix them or insert a new `provider: 'script'` discriminator into old configuration. A native target checks an explicit repository-relative static JSON/JSONC Wrangler config for an assets-only Worker. Named environments must exist, replace the whole assets object when overriding it, and explicitly configure routes when the top level owns routes. Preview/stable cannot share the same account+Worker, even with different environment names, or claim the same domains. Worker/account/url values are assertions, not silent config overrides. TOML, generated/plugin configs, Worker code, build hooks, bindings, service environments and unsupported deployment features use a script adapter.
+
+Native `deploy` preflights the frozen target, paths, runtime `CLOUDFLARE_API_TOKEN` and read-only Cloudflare deployment/version access before frozen-source install/build. Optional `CLOUDFLARE_ACCOUNT_ID` and effective Wrangler `account_id` must equal configured `accountId`. Read success does not prove future upload or domain-write permissions. Only Worker HTTP 404 plus code `10007` permits first deployment; ambiguous/empty responses, auth errors and rate limits fail. Install and lock Wrangler in the workspace; do not download or substitute an unrelated CLI during deployment. Recheck configuration and symlink containment after build.
+
+The native provider writes `/.well-known/repoctl-deployment.json` in assets with the full deployment identity; an existing file must already match that identity. Confirmation requires the latest active version at 100% with exact `repoctl-docs:<deploymentId>` annotation, never a historical match. Matching active identity reuses the remote version without another upload. New uploads must match Wrangler's Worker/environment/version and the active API result. This confirms provider state; optional target `readiness` adds exact public HTTP identity verification.
+
+The selected site build and provider/deployment phase receive frozen `REPO_DOCS_*` context. Frozen-source installation removes every inherited `REPO_DOCS_*` variable, retains ordinary CI/package-manager environment and lifecycle scripts, and sets `LEFTHOOK=0`; unrelated sites built by postinstall use their own defaults. The caller's environment is not mutated. Script adapters receive `REPO_DOCS_SITE`, `REPO_DOCS_CHANNEL`, `REPO_DOCS_SOURCE_SHA`, `REPO_DOCS_TREE_SHA`, `REPO_DOCS_RELEASE_ID`, `REPO_DOCS_DEPLOYMENT_ID`, `REPO_DOCS_URL` and `REPO_DOCS_RESULT_FILE`; write `{ versionId, url? }` to the result file only after provider verification. Native targets return that result directly. Credentials never enter the frozen identity.
+
+Both providers keep revision-checked claims and stable snapshots. Retry unknown uploads that lack a saved verification receipt, or final checkpoint failures with readiness disabled, using the same release/correction inputs: installation and rebuild still run, then reconciliation decides whether upload is needed. Failed retry preflight/build must retain an existing `deploying` claim. A different stable deployment cannot replace it; serialized latest-main preview can supersede an older preview. Already completed deployments skip. Older pending script snapshots keep their exact configuration and original source after live configuration moves to native targets. Never rewrite snapshots, republish npm to retry docs, or fake a stable completion record.
+
+Opt in per target with `readiness: {}` or bounded `timeoutMs`/`requestTimeoutMs`. Use an explicit HTTPS target URL; fetch only its origin-root manifest, without credentials, redirects or caching. Native targets stamp the manifest. Script targets must publish `schemaVersion: 1`, site/channel/deploymentId/sourceSha/treeSha from the supplied `REPO_DOCS_*` context, and releaseId only for stable; do not recompute the corrected tree or replace Nimbus `_headers`. A readiness receipt permits only a nonempty control-free versionId (≤512 characters) and optional HTTP(S) URL without credentials/query/fragment.
+
+Provider confirmation persists `verifying` plus its receipt before public HTTP. Timeout/finalization failure keeps the previous fully verified current, although public traffic may already serve the new version. Same-deployment retries skip frozen install/build/upload: native targets recheck the saved active version before polling and finalization; scripts reuse the receipt without rerunning deployScript. The workflow bootstrap install still runs. Another stable deployment cannot replace verifying, and saved stable policy/URL survive changes/removal on main. Never fall back to uploading because readiness failed.
+
+`deployDocs` success/skip may include `DocsDeploymentReport`; failure throws `DocsDeploymentError` with safe `.report`. Stages are plan/preflight/install/build/provider/readiness/finalize with explicit skips, monotonic elapsedMs, upload/reconcile and optional failedStage/resumablePhase. `--json` writes result/failure JSON only to stdout and streams child output live to stderr; `DocsOptions.json` selects that transport programmatically. Failures exit nonzero. Known repoctl failures retain fixed reason codes and actionable guidance. Generated reports omit raw exceptions/response bodies/credentials; scripts own their terminal logs. Escaped `GITHUB_STEP_SUMMARY` is best-effort: `summary-write-failed` warns without changing the outcome or hiding the primary failure.
+
 ## init
 
 Purpose: bootstrap workspace metadata plus recommended tooling defaults.
@@ -80,6 +106,8 @@ Usage:
 - `--json` emits the structured report only and still exits non-zero when blocking failures exist
 - `--out <file>` persists the text or JSON report and still exits non-zero when blocking failures exist
 
+Text and Markdown show stable rule IDs, exact affected paths and manifest fields. Identical findings share an explanation and fix while retaining every path and original check count; different reasons, fixes and suppressions stay separate. Use the displayed ID with `--rules`, for example `repo doctor --rules template-instance-drift`. Grouped display never changes statuses, effective totals, suppression policy or full individual JSON records. Use `--redact` before sharing local paths.
+
 ```bash
 repo doctor --list-rules
 repo doctor --rules root-scripts,package-manager --strict
@@ -105,6 +133,10 @@ Preview the complete operation with `repo upgrade --dry-run`, `--json` or `--mar
 
 Root assets use old-upstream/local/new-upstream three-way merging. Commit `.repoctl/baselines/root/` to preserve the upstream records across clones; record updates are reviewed in each file's `baseline` plan entry and applied atomically with that file. Independent changes merge automatically, while conflicting files and their baselines stay unchanged. Local deletion is never undone. API results expose unresolved `conflicts`; CLI preview and apply exit with code 1 when conflicts remain. Saved plans are reviewed write payloads; their hashes detect stale inputs and inconsistent content, not authorship. Generated app/package directories are outside this feature.
 
+New workspace overrides are checked against declarations in the proposed package membership and `commands.deps.groups`. Scope expansion or incompatible replacements produce `workspace-override-policy` conflicts, including with `--yes`/`--overwrite`. Inspect `workspacePolicy.findings` for affected manifests/groups and both value fingerprints. New parent-qualified selectors and non-semver replacements are `unverified`; ordinary upgrade requires explicit file selection, automatic maintenance rejects them, and reviewed saved-plan apply remains available. To retain an individual value or its absence, commit `commands.upgrade.keep` entries with `file: 'pnpm-workspace.yaml'`, `path: ['overrides', selector]`, `reason`, copied `upstreamHash`/`localHash`, and optional inclusive UTC `expires`. Regenerate the plan after configuration changes. Changed upstream/local values and elapsed expiry invalidate the decision; apply also checks configuration, inspected manifests and the proposed package set. Do not replace scoped overrides with global ones to silence this check. Existing template-instance `excludedPaths` and file selections remain separate.
+
+A recognized automatic default hook migration marks unverified override additions as `deferred` and leaves them absent. Preview again afterwards, then explicitly review/select or apply the new saved plan to accept them. Hard conflicts and protected skips of required files block every member of an atomic group, including explicit partial selection; preset-owned targets and preserved local deletions cannot leave hooks partially migrated. Automatic maintenance preparation and the independent publisher reject both `unverified` and `deferred`; finish the ordinary hook migration and override review before retrying maintenance.
+
 Upgrade apply holds `.repoctl/upgrade.lock` through validation, no-op detection, writes, rollback and cleanup. It never removes colliding recovery files, changed recovery bytes or replacement directories. After an interruption, confirm no writer is active and recover retained backups before removing the lock and regenerating the plan.
 
 Versioned migrations appear in `migrations` with stable IDs and affected files. The Changesets-to-pnpm migration starts at template 1.1.0. Use `--from-version <exact-semver>` only when the old version is known; dependency ranges are not version evidence. Unknown sources adopt only recognized legacy formats. Commit `.repoctl/migrations/ledger.json` when created; its cursor covers migrations, not all assets. Preview writes nothing. Pending/failed bytes and completed diffs are reviewed together; migration groups cannot be split, and completed is written only at the end of a successful migration transaction. Re-preview pending/failed attempts to see already-applied versus remaining files; third-state local edits block recovery and retain attempt-specific backups. The shared `.repoctl/upgrade.lock` is never stolen by age; confirm no writer is active and recover pending backups before clearing it. Recovery performs no network/publish actions or historical script execution.
@@ -458,3 +490,7 @@ Automatic maintenance can complete the built-in Changesets migration and update
 Preview `repo workspace prepare <exact-name-or-./directory> --mode prune|deploy --out ../empty-output --json`; save the plan outside the source workspace. Apply only after review with `repo workspace prepare --apply ../plan.json`. Prune uses local Turbo 2 and optional `--docker`; deploy uses exact pinned pnpm 10/11/12 with production dependencies, frozen lockfile, disabled lifecycle/pnpmfile hooks, optional `--offline`/explicit `--legacy`, and an existing built `--entry` or manifest main/single bin. Native version-specific injection and peer behavior remains authoritative. No application, image publishing or cloud deployment is executed.
 
 Native commands receive an isolated copy without node_modules, Git/operation/cache directories, real env files or named authentication files. Public .env.example/.env.sample remain. Source symlinks/special files, source-directed native write settings and inventories above 100,000 entries/1 GiB are unsupported. Output must be outside the workspace; links must remain inside the artifact. Publish files exclusively and commit the receipt last. Replays verify source/tool/config fingerprints and complete output; failures preserve concurrent edits and report retained paths. Review cleanupPending and recover partial output before removing a stale .repoctl/workspace-artifacts.lock. Do not hand-edit lockfiles or overwrite nonempty output. On Windows, transfer junction contents with an appropriate copy/archive mode.
+
+## Documentation build context
+
+Use `resolveDocsContext({ channel, url, previewOrigin, stableOrigin })` from `repoctl/docs-context` for public build metadata, plus `docsRobots`, `docsPreviewRobots` and ownership-aware `mergeDocsHeaders`. The pure entrypoint loads no provider, credentials or GitHub state. Default local builds are preview; `REPO_DOCS_CHANNEL=stable pnpm build` is allowed without deployment authorization. Distinct HTTP(S) origins are required and optional `REPO_DOCS_URL` must match. Review cached tasks with `repo env check build lint typecheck test --json`.

package/assets/.agents/skills/repoctl/references/config.md

@@ -7,7 +7,7 @@ Rule:
 - Load `repoctl.config.*`; rename legacy `monorepo.config.*`, which is no longer loaded.
 - Validate repoctl-owned fields before command side effects with `repo config validate --json`.
 - Native tooling passthrough and callbacks keep their extension boundary. Config modules are trusted executable project code.
-- Use `repo config inspect --command ai --set 'format="json"' --json` for shared defaults/project/CLI provenance. Contexts: ai, clean, create, deps, doctor, init, mirror, release, upgrade. Runtime selection is explained by each command's plan.
+- Use `repo config inspect --command ai --set 'format="json"' --json` for shared defaults/project/CLI provenance. Contexts: ai, clean, create, deps, doctor, docs, init, mirror, release, upgrade. Runtime selection is explained by each command's plan.
 - Reports redact env values and native tool payloads by default; `--redact` additionally hides local paths. For programmatic safe reports use `explainMonorepoConfig` or `validateConfigFile`; runtime config APIs retain callbacks and should not be serialized for sharing.
 - Git hooks use native `lefthook.yml`. Migrate old `tooling.lintStaged` and `tooling.husky` settings into that file.
 - Organization presets use `presets: [{ packageName, version }]` with an exact installed dependency and JSON-only `repoctl.preset.json`. Loading never imports package code, installs or fetches. Parents precede declaring presets, then the project and CLI; arrays replace at preset boundaries. `config inspect` exposes ordered layers and precise package/version sources.
@@ -70,6 +70,9 @@ Key areas:
 - upgrade: overwrite behavior and extra targets
 - init: skip steps for README/package.json/pnpm change intent setup
 - mirror: add or override env mirrors
+- docs: explicit sites with covered `packages`, a root `buildScript`, `preview`/`stable` targets, allowed `patchPaths` and optional per-package `releaseInputs`. Targets choose `{ deployScript, url? }` or `{ provider: 'cloudflare-workers', config, workerName, accountId, environment?, url? }`, never both. Native Cloudflare supports static assets-only JSON/JSONC configurations; freeze the nonsecret account identity, keep credentials in runtime environment secrets, and preserve old script snapshots for retry. See the docs section in `commands.md` for preflight and recovery boundaries.
+
+Both docs target variants accept optional `readiness: { timeoutMs?, requestTimeoutMs? }`. Omission means no public HTTP. `{}` requires an explicit HTTPS target URL without userinfo/query/fragment; probe the fixed origin-root `/.well-known/repoctl-deployment.json`. Positive integer defaults/limits: total 120000 ms / 1–600000, request 10000 ms / 1–30000. Runtime defaults do not alter stored config identity. Saved stable verification retains its original target and policy even if main removes them.
 
 ## `commands.doctor`
 
@@ -129,3 +132,9 @@ The root aggregates selected projects. Only explicit `relations` add compilation
 Existing references remain manually owned. Only newly added entries are recorded in `.repoctl/typescript-references.json`; commit that registry alongside the tsconfigs. Removing or excluding a project removes only entries recorded there. Editing/removing an owned entry blocks synchronization: restore it, or deliberately remove its registry entry to return ownership to the user. JSONC content outside the `references` value, BOM and line endings are preserved. Root aggregation and explicit edges produce stable relative config-file paths.
 
 Saved plans include input fingerprints and exact diffs. Applying a stale or edited plan fails before writes; reapplying an already completed plan is a no-op. A process lock at `.repoctl/typescript-references.lock` covers revalidation, writing, verification, rollback and cleanup. Changes stage together with backups and roll back on failure. If concurrent edits prevent safe rollback, the error names retained recovery files: preserve them, reconcile the business edit with the original backup, restore the ownership registry consistently and generate a new plan. A killed process can also leave `.repoctl-references-*.bak`/`.tmp` files; verify no writer remains, reconcile matching backups and the registry, then remove the stale lock. No recovery action overwrites a concurrent edit automatically.
+
+- upgrade `keep`: reviewed `pnpm-workspace.yaml` override decisions only; each entry has `file`, exact array `path`, nonempty `reason`, `upstreamHash`, `localHash`, and optional inclusive UTC `expires`. Copy fingerprints from `workspacePolicy.findings`; absence and null differ. Re-preview after editing configuration. Upstream/local value changes or expiry require renewed review.
+
+## Documentation channel rendering
+
+Provider target URLs and template origins must agree. `repoctl/docs-context` validates public channel/URL values only; it does not authorize deployments or stamp deployment manifests. Configure the Nimbus or VitePress deployment module with distinct preview/stable origins and keep channel/URL in task-local Turbo `env` hashes. Preview crawler restrictions must not disable local search. Preserve project-owned layouts and user/Nimbus `_headers` rules through the marked merge helper.

package/assets/.agents/skills/repoctl/references/dependencies.md

@@ -35,3 +35,5 @@ Only plain semver ranges and same-source npm aliases can migrate. An alias keeps
 Apply is bound to the same workspace and full input set. Stale YAML, changed manifests/policies, new packages, linked files, partial application and modified plan contents are rejected before writes. It uses the same staged replacements, backups and rollback as dependency fixes, across both YAML and JSON. A fully applied plan and a repeated migration are no-ops. If recovery cannot safely replace a concurrent edit, inspect the listed `.repoctl-deps-*.bak` originals, restore reviewed files, remove stale temporary files and generate a fresh plan; the concurrent edit is preserved.
 
 Public APIs are `checkCatalogs(cwd, options?)`, `planCatalogMigration(cwd, options)` and `applyCatalogMigrationPlan(cwd, plan)`. See [pnpm catalogs](https://pnpm.io/catalogs) for protocol semantics and [Syncpack](https://syncpack.dev/) for intentional version-group policy patterns.
+
+Workspace upgrade reuses dependency groups when evaluating new overrides. It scans the proposed workspace membership, reports selector expansion and declarations incompatible with replacement versions, and keeps unverified parent-qualified/non-semver cases explicit. Use fingerprint-bound `commands.upgrade.keep` decisions to retain reviewed local override values or absence; do not remove intentional cohorts merely to accept template defaults.

package/assets/.agents/skills/repoctl/references/templates.md

@@ -68,3 +68,9 @@ npm configuration supplies scoped registry/authentication. Never put credentials
 ## Existing-package generators
 
 Use `repo generate <vue-component|react-component|hono-route> <kebab-name> --package <exact-name-or-relative-dir> --json` to inspect source and behavior-test files before writing. Run without `--json` to apply; `--export` explicitly adds a named export to `src/index.ts` (or `--barrel`). `--directory` stays inside the selected package. Strict parameters, framework requirements, stale plans, symlinks and conflicting files fail before writes. Repeated identical generation is unchanged. Hono route registration remains an explicit printed next step. Validate generated output with build, ESLint/Stylelint, tsc/vue-tsc and tests. Keep `repo new` for whole new packages; it never overwrites existing directories.
+
+## Documentation channels
+
+Nimbus and VitePress use `repoctl/docs-context` with explicit `REPO_DOCS_CHANNEL` and `REPO_DOCS_URL` build inputs. Configure distinct preview/stable HTTP(S) origins in the local deployment module; paths belong to the framework base. Missing/empty channel defaults to preview; supplied URL must match the selected origin. Local stable builds require no token or release record.
+
+Keep preview banners, robots/meta/X-Robots-Tag restrictions and search independent: preview remains searchable with official AI exports. `mergeDocsHeaders` owns marked fields only and preserves user/Nimbus rules; malformed markers fail. Keep task-local Turbo env hashes and authored content/config/script inputs, and run `repo env check build lint typecheck test --json`. Both docs packages declare repoctl directly. Existing layouts remain project-owned; use reviewed template upgrades or manual integration.

package/dist/cli.mjs

@@ -1,4 +1,4 @@
-import { t as prepareAssets } from "./prepare-CiHv-JJL.mjs";
+import { t as prepareAssets } from "./prepare-awxaJLdj.mjs";
 import process from "node:process";
 //#region src/cli.ts
 async function main() {

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { _ as getAssetTargets$1, a as createTemplateCopyFilter, c as toPublishGitignorePath, d as templateChoices$1, f as assetsDir, g as assetTargets$1, h as templatesDir, i as arePublishedConfigAssetsPrepared, l as toWorkspaceAssetPath, m as skeletonDir, n as arePublishedGithubAssetsPrepared, o as shouldSkipTemplatePath, p as packageDir, r as sanitizePublishedWorkspaceContent, s as isGitignoreFile, t as prepareAssets, u as toWorkspaceGitignorePath } from "./prepare-CiHv-JJL.mjs";
+import { _ as getAssetTargets$1, a as createTemplateCopyFilter, c as toPublishGitignorePath, d as templateChoices$1, f as assetsDir, g as assetTargets$1, h as templatesDir, i as arePublishedConfigAssetsPrepared, l as toWorkspaceAssetPath, m as skeletonDir, n as arePublishedGithubAssetsPrepared, o as shouldSkipTemplatePath, p as packageDir, r as sanitizePublishedWorkspaceContent, s as isGitignoreFile, t as prepareAssets, u as toWorkspaceGitignorePath } from "./prepare-awxaJLdj.mjs";
 import path from "node:path";
 import fs, { access, lstat, mkdir, open, readFile, rm, writeFile } from "node:fs/promises";
 import { Buffer } from "node:buffer";

package/dist/{prepare-CiHv-JJL.mjs → prepare-awxaJLdj.mjs}

@@ -511,6 +511,23 @@ async function arePublishedGithubAssetsPrepared(repoRoot, assetRoot) {
 	}
 }
 //#endregion
+//#region src/prepare/template-manifest.ts
+/** Nested template assets are not rewritten by npm pack's workspace conversion. */
+function sanitizeTemplateManifest(content) {
+	const manifest = JSON.parse(content);
+	for (const field of [
+		"dependencies",
+		"devDependencies",
+		"optionalDependencies",
+		"peerDependencies"
+	]) {
+		const dependencies = manifest[field];
+		for (const [name, version] of Object.entries(dependencies ?? {})) if (name === "repoctl" && version === "workspace:*") dependencies[name] = "latest";
+		else if (/^(?:workspace|file|link|catalog):/.test(version)) throw new Error(`Template ${field}.${name} contains an unsupported source-local dependency`);
+	}
+	return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+//#endregion
 //#region src/prepare/index.ts
 function toPublishedAssetPath(target) {
 	return target === ".npmrc" ? "npmrc" : toPublishGitignorePath(target);
@@ -650,6 +667,8 @@ async function copyTemplates(repoRoot, overwriteExisting) {
 		const to = path$1.join(templatesDir, template.source);
 		const filter = (src) => !shouldSkipTemplatePath(from, src);
 		await copyEntry(from, to, overwriteExisting, filter);
+		const manifest = path$1.join(from, "package.json");
+		if (await pathExists(manifest)) await fs.writeFile(path$1.join(to, "package.json"), sanitizeTemplateManifest(await fs.readFile(manifest, "utf8")));
 		await renameGitignoreFiles(to);
 	}
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@icebreakers/monorepo-templates",
   "type": "module",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Built-in project templates and managed workspace assets for repoctl",
   "author": "ice breaker <hi@sonofmagic.top>",
   "license": "MIT",

package/templates/nimbus/AGENTS.md

@@ -5,8 +5,13 @@ This is a static Nimbus + Astro documentation site. Run commands in this workspa
 - Content lives in `src/content/docs/`; English uses the root and Chinese uses `zh/` with matching relative filenames. Keep both translations and links in sync. The directory tree supplies routes and navigation.
 - Layouts and components are project-owned. Keep modules small. Put styles in `src/styles/` so Stylelint checks every authored style.
 - Register MDX components in `src/components.ts`. Add a text conversion in `astro.config.ts` when a custom component conveys information that would otherwise disappear from Markdown.
-- Set the canonical `site` URL and project title in `astro.config.ts` before deployment. Static output is `dist/` and can be hosted anywhere.
+- Set channel origins in `src/lib/deployment.ts` and the project title in `astro.config.ts` before deployment. Static output is `dist/` and can be hosted anywhere.
 - Run `pnpm build`, `pnpm lint`, and `pnpm typecheck`. `typecheck` combines Astro diagnostics with TypeScript checks. Search uses the production Pagefind index; verify it with `pnpm preview` after building.
 - Verify `/llms.txt`, `/zh/llms.txt`, `/llms-full.txt`, and each page's `/index.md` and `/index.mdx`. Keep private content outside public content collections; `noindex` is not access control.
 - `draft: true` excludes unfinished pages from production. When adding a page, create its translation before publishing so the language switch remains valid.
 - Keep `nimbus.json` and `UPSTREAM.md` when upgrading. Review Nimbus migrations and project-owned changes before advancing the reviewed version.
+
+- Configure distinct preview/stable HTTP(S) origins in `src/lib/deployment.ts`; use Astro `base` for a subpath. `repoctl/docs-context` reads only explicit public channel/URL values and requires no credentials for local builds. Keep this workspace's repoctl dependency and Turbo env/input declarations.
+- Preview is the local default. Preview uses a bilingual notice and robots/meta/header restrictions while preserving Pagefind bodies and official AI exports. Content `noindex` is separate; honor explicit `searchable: true`.
+- Keep the channel integration after Nimbus. Merge `_headers` using repoctl ownership markers, preserving user security/cache rules and Nimbus discovery rules. Verify preview → stable → preview builds in the same directory, real search results, both languages and no-JavaScript content.
+- Existing layouts are project-owned. Review template upgrades or integrate the helper manually; root managed upgrades do not replace them.

package/templates/nimbus/README.md

@@ -12,7 +12,7 @@ pnpm lint
 pnpm typecheck
 ```
 
-Edit `src/content/docs/` and its `zh/` translations. Set your project title and canonical site URL in `astro.config.ts` before publishing `dist/` to a static host. Search is available after a production build.
+Edit `src/content/docs/` and its `zh/` translations. Set your project title in `astro.config.ts` and channel origins in `src/lib/deployment.ts` before publishing `dist/` to a static host. Search is available after a production build.
 
 机器可读入口包括 `/llms.txt`、`/zh/llms.txt`、`/llms-full.txt`，以及页面的 `/index.md` 和 `/index.mdx`。Nimbus 还会生成 `/.well-known/ard.json`、`/.well-known/ai-catalog.json` 和 `dist/_headers` 中的发现响应头。静态托管需要应用这些响应头；不支持 `_headers` 的主机应配置等效规则。使用子路径部署时，发现文件仍须发布到域名根目录的 `/.well-known/`，并在那里应用对应响应头规则。详见 `AGENTS.md` 和 `UPSTREAM.md`。
 
@@ -37,3 +37,16 @@ pnpm typecheck
 ```
 
 不要只修改审阅版本来跳过迁移。部署前检查发现文件、首页 Link 响应头，以及中英文页面和机器可读入口。
+
+## Preview and stable builds / 预览与正式构建
+
+Set distinct `previewOrigin` and `stableOrigin` in `src/lib/deployment.ts`; `astro.config.ts` consumes the same public context as page metadata, robots and the official Nimbus AI/discovery endpoints. With no channel configured, local builds use preview. Both commands work without deployment credentials:
+
+```sh
+REPO_DOCS_CHANNEL=preview pnpm build
+REPO_DOCS_CHANNEL=stable pnpm build
+```
+
+`REPO_DOCS_URL`, when nonempty, must match the selected origin. Configure a subpath with Astro `base`, not an origin pathname. The build rejects a hosting environment that changes Nimbus's resolved origin. The template's Turbo tasks hash both channel inputs and all authored content/configuration/scripts.
+
+预览站显示未发布提示，输出 robots、meta 和 X-Robots-Tag 禁止搜索引擎收录策略，同时保留 Pagefind 站内搜索、Markdown 和 LLM 导出。内容自身的 `noindex` 与搜索资格分开处理，显式 `searchable: true` 仍可搜索。正式构建移除渠道专属限制，保留内容的 `noindex`。`_headers` 只增删 repoctl 标记的部分，保留用户缓存/安全策略和 Nimbus 发现响应头；标记损坏会直接失败。禁止收录不是访问控制。

package/templates/nimbus/UPSTREAM.md

@@ -32,3 +32,9 @@ The `0.16.0` → `0.17.0` review follows the installed package's `nimbus-docs mi
 The site remains static. Its existing Markdown/MDX and LLM endpoint factories stay valid. Optional copied-sidebar, browser WebMCP and server-rendering changes are not adopted. There is no project `skills/` directory to publish. Existing `robots.txt` policy is preserved; the new starter's optional AI training Content Signals are not adopted implicitly.
 
 For a subpath deployment, publish the generated `.well-known/` directory at the origin root and apply its header rules there. Hosts that do not consume `_headers` need equivalent native header configuration; see the [agent deployment guidance](https://nimbus-docs.com/ai/docs-for-agents/).
+
+## repoctl channel integration
+
+The project-owned `src/lib/deployment.ts` resolves `repoctl/docs-context` before `defineNimbusConfig`, so Nimbus 0.17.0 receives one origin for Astro metadata, baked Markdown/LLM endpoints and agent discovery. A final config assertion rejects hosting-environment origin drift. Preview disables sitemap generation but does not mark content entries noindex, preserving Nimbus discovery and Pagefind indexing. The local head adds crawler restrictions independently; explicit content `searchable: true` is honored even with authored noindex.
+
+The channel integration follows Nimbus's build hook and merges only marked repoctl X-Robots-Tag fields into `_headers`. Nimbus's discovery markers, Link headers and owner headers remain intact across channel switches. Preview/stable is a repoctl adaptation, not an upstream version migration; the reviewed Nimbus 0.17.0 baseline is unchanged. Existing origin-root `.well-known/` hosting instructions still apply with Astro `base`.

package/templates/nimbus/astro.config.ts

@@ -1,18 +1,20 @@
 import nimbus, { defineConfig as defineNimbusConfig } from '@cloudflare/nimbus-docs'
 import { defineConfig } from 'astro/config'
+import { deployment } from './src/lib/deployment'
+import { docsChannel } from './src/lib/deployment/integration'
 
 export default defineConfig({
   output: 'static',
   // Keep the Pagefind loader external so Vite finalizes dynamic imports before Astro renders it.
   vite: { build: { assetsInlineLimit: 0 } },
   integrations: [nimbus(defineNimbusConfig({
-    // Set your production origin before publishing.
-    site: 'https://docs.example.com',
+    site: deployment.origin,
     title: 'Project docs',
     description: 'Guides and examples for your project.',
     locale: 'en',
     github: null,
   }), {
+    sitemap: !deployment.preview,
     icons: false,
     rules: {
       'nimbus/frontmatter-shape': 'error',
@@ -24,5 +26,5 @@ export default defineConfig({
         Aside: { revision: '1', render: ({ children }) => children },
       },
     },
-  })],
+  }), docsChannel(deployment)],
 })

package/templates/nimbus/package.json

@@ -29,6 +29,7 @@
     "eslint-plugin-astro": "^3.2.1",
     "eslint-plugin-mdx": "^3.8.1",
     "pagefind": "^1.5.2",
+    "repoctl": "latest",
     "typescript": "^6.0.3"
   }
 }

package/templates/nimbus/src/components/head.astro

@@ -1,6 +1,8 @@
 ---
 import { withBase } from '@cloudflare/nimbus-docs/runtime'
+import { docsPreviewRobots } from 'repoctl/docs-context'
 import { config } from 'virtual:nimbus/config'
+import { deployment } from '../lib/deployment'
 
 interface Props {
   title: string
@@ -28,11 +30,11 @@ const structuredData = JSON.stringify({
 <title>{fullTitle}</title>
 <meta name="generator" content={Astro.generator} />
 <meta name="description" content={description} />
-{noindex && <meta name="robots" content="noindex" />}
+{(deployment.preview || noindex) && <meta name="robots" content={deployment.preview ? docsPreviewRobots : 'noindex'} />}
 <link rel="icon" type="image/svg+xml" href={withBase('/favicon.svg', base)} />
 <link rel="stylesheet" href={withBase('/_nimbus/shiki.css', base)} />
 <link rel="canonical" href={canonical} />
-<link rel="sitemap" href={withBase('/sitemap-index.xml', base)} />
+{!deployment.preview && <link rel="sitemap" href={withBase('/sitemap-index.xml', base)} />}
 {markdownUrl && <link rel="alternate" type="text/markdown" href={new URL(withBase(markdownUrl, base), Astro.site)} />}
 <meta property="og:title" content={fullTitle} />
 <meta property="og:type" content="article" />

package/templates/nimbus/src/content/docs/get-started.mdx

@@ -31,6 +31,6 @@ pnpm build
 pnpm preview
 ```
 
-The build writes `dist/` and creates the search index. Set your production URL in `astro.config.ts` before publishing.
+The build writes `dist/` and creates the search index. Set channel origins in `src/lib/deployment.ts` before publishing.
 
 Continue with the [writing guide](/writing/).

package/templates/nimbus/src/content/docs/zh/get-started.mdx

@@ -31,6 +31,6 @@ pnpm build
 pnpm preview
 ```
 
-构建会生成 `dist/` 和搜索索引。发布前，在 `astro.config.ts` 中填写正式站点地址。
+构建会生成 `dist/` 和搜索索引。发布前，在 `src/lib/deployment.ts` 中填写预览与正式站点 origin。
 
 继续阅读[写作指南](/zh/writing/)。

package/templates/nimbus/src/layouts/docs.astro

@@ -5,6 +5,7 @@ import { config } from 'virtual:nimbus/config'
 import Head from '../components/head.astro'
 import Search from '../components/search/index.astro'
 import Sidebar from '../components/sidebar.astro'
+import { deployment } from '../lib/deployment'
 import { labels } from '../lib/locale'
 import '../styles/site.css'
 
@@ -13,6 +14,9 @@ const { title, description, sidebar, headings, markdownUrl, chinese, alternate,
 const text = labels[chinese ? 'zh' : 'en']
 const base = import.meta.env.BASE_URL
 const indexUrl = withBase(chinese ? '/zh/llms.txt' : '/llms.txt', base)
+const searchableContent = !draft && (searchable === true || (searchable !== false && !noindex))
+const englishPath = chinese ? withBase(alternate, base) : Astro.url.pathname
+const chinesePath = chinese ? Astro.url.pathname : withBase(alternate, base)
 ---
 
 <!doctype html>
@@ -21,11 +25,20 @@ const indexUrl = withBase(chinese ? '/zh/llms.txt' : '/llms.txt', base)
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <Head title={title} description={description} markdownUrl={markdownUrl} noindex={noindex || draft} chinese={chinese} />
-    <link rel="alternate" hreflang={chinese ? 'en' : 'zh-CN'} href={new URL(withBase(alternate, base), Astro.site)} />
+    <link rel="alternate" hreflang="en" href={new URL(englishPath, Astro.site)} />
+    <link rel="alternate" hreflang="zh-CN" href={new URL(chinesePath, Astro.site)} />
+    <link rel="alternate" hreflang="x-default" href={new URL(englishPath, Astro.site)} />
     <link rel="alternate" type="text/plain" href={indexUrl} title={text.index} />
   </head>
   <body>
     <a class="skip-link" href="#main-content">{text.skip}</a>
+    {deployment.preview && (
+      <aside class="docs-preview-notice" data-pagefind-ignore aria-label={text.previewLabel}>
+        {text.previewNotice}
+        {' '}
+        <a href={new URL(withBase(chinese ? '/zh/' : '/', base), deployment.stableOrigin)}>{text.stableDocs}</a>
+      </aside>
+    )}
     <header class="site-header">
       <a class="brand" href={withBase(chinese ? '/zh/' : '/', base)}>{config.title}</a>
       <a class="language-link" href={withBase(alternate, base)} lang={chinese ? 'en' : 'zh-CN'}>{chinese ? 'English' : '简体中文'}</a>
@@ -40,7 +53,7 @@ const indexUrl = withBase(chinese ? '/zh/llms.txt' : '/llms.txt', base)
         <a class="index-link" href={indexUrl}>llms.txt ↗</a>
       </aside>
       <main id="main-content" tabindex="-1">
-        <div data-pagefind-body={searchable !== false && !noindex && !draft ? '' : undefined} data-pagefind-ignore={searchable === false || noindex || draft ? '' : undefined}>
+        <div data-pagefind-body={searchableContent ? '' : undefined} data-pagefind-ignore={searchableContent ? undefined : ''}>
           <h1>{title}</h1>
           {description && <p class="description">{description}</p>}
           <article><slot /></article>

package/templates/nimbus/src/lib/deployment/integration.ts

@@ -0,0 +1,28 @@
+import type { AstroIntegration } from 'astro'
+import type { DocsContext } from 'repoctl/docs-context'
+import { readFile, writeFile } from 'node:fs/promises'
+import { mergeDocsHeaders } from 'repoctl/docs-context'
+
+/** Run after Nimbus so its discovery headers remain present in either channel. */
+export function docsChannel(context: DocsContext): AstroIntegration {
+  return {
+    name: 'repoctl-docs-channel',
+    hooks: {
+      'astro:config:done': ({ config }) => {
+        if (!config.site || new URL(config.site).origin !== context.origin) {
+          throw new Error('Resolved Nimbus site differs from the documentation channel origin')
+        }
+      },
+      'astro:build:done': async ({ dir }) => {
+        const filename = new URL('_headers', dir)
+        const existing = await readFile(filename, 'utf8').catch((error: NodeJS.ErrnoException) => {
+          if (error.code !== 'ENOENT') {
+            throw error
+          }
+          return ''
+        })
+        await writeFile(filename, mergeDocsHeaders(existing, context))
+      },
+    },
+  }
+}

package/templates/nimbus/src/lib/deployment.ts

@@ -0,0 +1,10 @@
+import process from 'node:process'
+import { resolveDocsContext } from 'repoctl/docs-context'
+
+// Configure distinct origins here; Astro's base option owns any path prefix.
+export const deployment = resolveDocsContext({
+  channel: process.env.REPO_DOCS_CHANNEL,
+  url: process.env.REPO_DOCS_URL,
+  previewOrigin: 'https://preview.docs.example.com',
+  stableOrigin: 'https://docs.example.com',
+})

package/templates/nimbus/src/lib/locale.ts

@@ -24,6 +24,9 @@ export function localizeSidebar(items: SidebarItem[], chinese: boolean): Sidebar
 
 export const labels = {
   en: {
+    previewLabel: 'Documentation preview',
+    previewNotice: 'Development documentation includes unreleased changes.',
+    stableDocs: 'Read the stable documentation',
     navigation: 'On this site',
     contents: 'On this page',
     skip: 'Skip to content',
@@ -36,6 +39,9 @@ export const labels = {
     index: 'Documentation index',
   },
   zh: {
+    previewLabel: '文档预览',
+    previewNotice: '开发版文档，包含尚未发布的功能。',
+    stableDocs: '查看正式版文档',
     navigation: '站点导航',
     contents: '本页目录',
     skip: '跳转到正文',

package/templates/nimbus/src/pages/robots.txt.ts

@@ -1,16 +1,11 @@
 import { withBase } from '@cloudflare/nimbus-docs/runtime'
-import { config } from 'virtual:nimbus/config'
+import { docsRobots } from 'repoctl/docs-context'
+import { deployment } from '../lib/deployment'
 
 export const prerender = true
 
 export function GET() {
-  const body = [
-    'User-agent: *',
-    'Allow: /',
-    '',
-    `Sitemap: ${new URL(withBase('/sitemap-index.xml', import.meta.env.BASE_URL), config.site).href}`,
-    '',
-  ].join('\n')
+  const body = docsRobots(deployment, new URL(withBase('/sitemap-index.xml', import.meta.env.BASE_URL), deployment.origin).href)
 
   return new Response(body, {
     headers: { 'Content-Type': 'text/plain; charset=utf-8' },

package/templates/nimbus/src/styles/site.css

@@ -1,5 +1,13 @@
 @import './base.css';
 
+.docs-preview-notice {
+  padding: 0.75rem 1.5rem;
+  color: var(--ink);
+  text-align: center;
+  background: var(--soft);
+  border-bottom: 1px solid var(--line);
+}
+
 .site-header {
   display: flex;
   align-items: center;

package/templates/nimbus/turbo.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://turborepo.com/schema.json",
+  "extends": [
+    "//"
+  ],
+  "tasks": {
+    "build": {
+      "env": [
+        "$TURBO_EXTENDS$",
+        "REPO_DOCS_CHANNEL",
+        "REPO_DOCS_URL"
+      ],
+      "inputs": [
+        "$TURBO_DEFAULT$"
+      ]
+    },
+    "lint": {
+      "env": [
+        "$TURBO_EXTENDS$",
+        "REPO_DOCS_CHANNEL",
+        "REPO_DOCS_URL"
+      ],
+      "inputs": [
+        "$TURBO_DEFAULT$"
+      ]
+    },
+    "typecheck": {
+      "env": [
+        "$TURBO_EXTENDS$",
+        "REPO_DOCS_CHANNEL",
+        "REPO_DOCS_URL"
+      ],
+      "inputs": [
+        "$TURBO_DEFAULT$"
+      ]
+    },
+    "test": {
+      "env": [
+        "$TURBO_EXTENDS$",
+        "REPO_DOCS_CHANNEL",
+        "REPO_DOCS_URL"
+      ],
+      "inputs": [
+        "$TURBO_DEFAULT$"
+      ]
+    }
+  }
+}

package/templates/react-lib/package.json

@@ -5,7 +5,9 @@
   "private": true,
   "description": "React component library with explicit JavaScript, types and CSS exports",
   "license": "MIT",
-  "sideEffects": ["**/*.css"],
+  "sideEffects": [
+    "**/*.css"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -15,8 +17,14 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": ["LICENSE", "README.md", "dist"],
-  "engines": { "node": "^22.23.4 || ^24.22.1 || >=26.12.1" },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist"
+  ],
+  "engines": {
+    "node": "^22.23.4 || ^24.22.1 || >=26.12.1"
+  },
   "scripts": {
     "build": "vite build",
     "lint": "eslint . && stylelint \"src/**/*.css\"",

package/templates/vitepress/.vitepress/config.ts

@@ -9,7 +9,7 @@ import { mermaidMarkdown } from './mermaid/markdown'
 import { createNav, createSidebars } from './navigation/routes'
 import { createPageHead } from './seo'
 
-const deployment = getDocsDeployment(process.env.REPO_DOCS_CHANNEL)
+const deployment = getDocsDeployment(process.env.REPO_DOCS_CHANNEL, process.env.REPO_DOCS_URL)
 
 export default defineConfig<DocsThemeConfig>({
   outDir: '.vitepress/dist',

package/templates/vitepress/.vitepress/deployment/index.ts

@@ -1,37 +1,23 @@
+import type { DocsContext } from 'repoctl/docs-context'
 import type { DefaultTheme } from 'vitepress'
+import { docsRobots, mergeDocsHeaders, resolveDocsContext } from 'repoctl/docs-context'
 
 export const stableOrigin = 'https://repo.icebreaker.top'
 export const previewOrigin = 'https://next.repo.icebreaker.top'
 
-export interface DocsDeployment {
-  channel: 'preview' | 'stable'
-  preview: boolean
-  origin: string
-}
+export type DocsDeployment = DocsContext
 
 export interface DocsThemeConfig extends DefaultTheme.Config {
   docsPreview?: boolean
 }
 
-export function getDocsDeployment(channel: string | undefined): DocsDeployment {
-  if (channel !== undefined && channel !== '' && channel !== 'preview' && channel !== 'stable') {
-    throw new Error(`Unsupported documentation channel: ${channel}`)
-  }
-  const preview = channel !== 'stable'
-  return {
-    channel: preview ? 'preview' : 'stable',
-    preview,
-    origin: preview ? previewOrigin : stableOrigin,
-  }
+export function getDocsDeployment(channel: string | undefined, url?: string): DocsDeployment {
+  return resolveDocsContext({ channel, url, previewOrigin, stableOrigin })
 }
 
 export function crawlerFiles(deployment: DocsDeployment) {
   return {
-    robots: deployment.preview
-      ? 'User-agent: *\nDisallow: /\n'
-      : `User-agent: *\nAllow: /\nDisallow: /_headers\n\nSitemap: ${stableOrigin}/sitemap.xml\n`,
-    headers: deployment.preview
-      ? '/*\n  X-Robots-Tag: noindex, nofollow, noarchive\n'
-      : '',
+    robots: docsRobots(deployment),
+    headers: mergeDocsHeaders('', deployment),
   }
 }