@kungfu-tech/buildchain 3.0.4-alpha.1 → 3.0.4-alpha.11

package/docs/cli.md

@@ -51,7 +51,8 @@ published, pnpm may block the install through a minimum release-age policy. In
 that case, add a temporary package/version-specific `minimumReleaseAgeExclude`
 entry, such as `@kungfu-tech/buildchain@3.0.0`, and remove it once the package
 has aged past the normal policy window. Do not replace that with a broad
-registry or scope-wide exclude.
+registry or scope-wide exclude. Paper scaffold and migration maintain the
+exact current entry in `pnpm-workspace.yaml` before refreshing the lockfile.
 
 Use the package API directly inside JavaScript build scripts:
 
@@ -111,6 +112,19 @@ Use `dist/site/manual-registry.json` to find the packaged operating manuals and
 their SHA-256 digests. Use `dist/site/buildchain-contract.json` to verify the
 floating-ref contract world for a runtime such as `@v3`.
 
+For exhaustive lookup, use the generated references rather than scanning this
+conceptual guide:
+
+- [`cli-reference.md`](cli-reference.md) is projected from the governed usage
+  model and runtime command registry. `buildchain <path> --help` is intercepted
+  before dispatch at every listed path, exits zero, and has no command side
+  effects.
+- [`node-api-reference.md`](node-api-reference.md) is projected from
+  `package.json#exports` and exact ESM export declarations. The packaged
+  `dist/site/node-api-registry.json` carries the same per-symbol signatures,
+  parameters, conservative return/error boundaries, side-effect classification,
+  maturity, example import, and source location.
+
 ## Commands
 
 `buildchain create github-artifact-attestation-policy` seals the expected

package/docs/getting-started.md

@@ -0,0 +1,167 @@
+---
+status: active
+period: ongoing
+theme: buildchain-golden-path
+doc_type: technical-guide
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-08-01
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-01
+  invisible_context: not asserted
+---
+
+# Buildchain Golden Path
+
+This path is for a repository maintainer adopting Buildchain for the first
+time. It takes about 15–30 minutes and ends with five inspectable outcomes: an
+exact package pin, a declared project type, a valid local configuration, a thin
+reusable workflow caller, and a Release Passport inspection.
+
+Use this page for the first successful pass. Move to the advanced manuals only
+after the local checks below are green.
+
+## 1. Create a clean consumer and install an exact version
+
+```bash
+consumer_dir="$(mktemp -d)"
+cd "$consumer_dir"
+npm init -y
+buildchain_version="$(npm view @kungfu-tech/buildchain version)"
+pnpm add -D "@kungfu-tech/buildchain@$buildchain_version"
+pnpm exec buildchain --version
+```
+
+The package manager records the exact resolved version in `package.json` and
+the lockfile. Review that version before committing it; do not leave a floating
+range in a release repository.
+
+## 2. Choose the project type and initialize
+
+Start with `package` for a Node package. Other supported types are `native`,
+`web-surface`, `infra-contract`, `publication-artifact`, and
+`anchored-package`.
+
+```bash
+pnpm exec buildchain init --type package --package-manager pnpm
+```
+
+Inspect the two generated files before continuing:
+
+```bash
+sed -n '1,220p' .buildchain/buildchain.toml
+sed -n '1,220p' .github/workflows/build.yml
+```
+
+`buildchain.toml` owns repository lifecycle declarations. The workflow is a
+thin caller of Buildchain's reusable workflow; it is not a second release
+implementation.
+
+## 3. Validate the local contract
+
+```bash
+pnpm exec buildchain validate \
+  --require-version-state \
+  --require-lifecycle-stages install,build,verify
+pnpm exec buildchain doctor --json
+```
+
+If the generated lifecycle commands do not match the repository, edit only
+`.buildchain/buildchain.toml`, then rerun both checks. See
+[Lifecycle Protocol](lifecycle-protocol.md) for the normative fields.
+
+## 4. Inspect the reusable workflow and release dry-run
+
+The generated caller should contain one reusable `uses:` edge and a manual
+`buildchain-ref` input for bounded train validation:
+
+```bash
+rg -n 'uses:|buildchain-ref:' .github/workflows/build.yml
+pnpm exec buildchain release --dry-run \
+  --target-ref alpha/v3/v3.0 \
+  --json
+```
+
+The dry-run explains legal source refs, tags, version state, and publication
+effects. It does not move refs, edit files, or publish packages.
+
+## 5. Create and inspect a local Release Passport example
+
+This example creates a source-bound local Passport through the public Node API,
+then reads it through the CLI. It is learning evidence, not publication
+authority.
+
+```bash
+mkdir -p .buildchain/golden-path
+node --input-type=module <<'EOF'
+import fs from "node:fs";
+import { createReleasePassport } from "@kungfu-tech/buildchain";
+
+const passport = createReleasePassport({
+  repository: "example/consumer",
+  tag: "v0.1.0-alpha.0",
+  sourceSha: "a".repeat(40),
+  assets: [{ name: "consumer.tgz", sha256: "b".repeat(64) }],
+});
+fs.writeFileSync(
+  ".buildchain/golden-path/buildchain.release.json",
+  `${JSON.stringify(passport, null, 2)}\n`,
+);
+EOF
+
+pnpm exec buildchain inspect release \
+  --passport .buildchain/golden-path/buildchain.release.json \
+  --json
+```
+
+For a real release, the protected Buildchain workflow creates the Passport from
+the exact source, artifact, controller, and publication evidence. See
+[Release Passport](release-passport.md); do not promote this local example.
+
+## You are done when
+
+- the dependency and lockfile contain one exact Buildchain version;
+- `.buildchain/buildchain.toml` declares the intended project type and lifecycle;
+- `validate` and `doctor` succeed;
+- `.github/workflows/build.yml` remains a thin reusable-workflow caller;
+- the release dry-run and local Passport inspection both return structured output.
+
+The repository test `pnpm run check:golden-path` reproduces this path in a new
+temporary consumer using the locally packed Buildchain package.
+
+## Choose the next manual
+
+| Intent | Next page |
+| --- | --- |
+| Change lifecycle commands or version files | [Lifecycle Protocol](lifecycle-protocol.md) |
+| Configure native matrices, runners, caches, or artifacts | [Reusable Build Surface](reusable-build-surface.md) |
+| Look up a command | [Generated CLI Reference](cli-reference.md) |
+| Import the Node toolkit | [Generated Node API Reference](node-api-reference.md) |
+| Understand protected branches and tags | [Release Flow](release-flow.md) |
+| Verify published evidence | [Release Passport](release-passport.md) |
+
+## Troubleshooting
+
+- `already exists`: initialization is no-overwrite by default. Inspect the
+  existing files; use `--force` only for an intentional replacement.
+- missing lifecycle stage: add the named stage to
+  `.buildchain/buildchain.toml`; do not weaken the validation command.
+- package release-age policy: add a temporary, package-and-version-specific
+  `minimumReleaseAgeExclude`, then remove it after the normal window.
+- unsure about syntax: run `buildchain <path> --help`. Help is intercepted
+  before command dispatch and is side-effect free at every governed path.
+
+## Small glossary
+
+- **project type**: the repository shape selected by `buildchain init`.
+- **lifecycle**: repository-owned install, build, verify, and publish commands.
+- **reusable workflow**: Buildchain-owned GitHub Actions control plane called by
+  a thin consumer workflow.
+- **Release Passport**: source- and artifact-bound release evidence, not a
+  release trigger.
+- **train ref**: a temporary validation runtime; never a production dependency.

package/docs/install.md

@@ -72,18 +72,17 @@ age policy blocks the install, use a temporary package/version-specific
 `minimumReleaseAgeExclude` entry instead of weakening the registry policy for
 all packages:
 
-```json
-{
-  "pnpm": {
-    "minimumReleaseAgeExclude": [
-      "@kungfu-tech/buildchain@3.0.0"
-    ]
-  }
-}
+```yaml
+minimumReleaseAgeExclude:
+  - '@kungfu-tech/buildchain@3.0.0'
 ```
 
 Remove that entry after the package is old enough for the repository's normal
 policy. Do not use a broad exclude such as `@kungfu-tech/*` for this case.
+Buildchain-managed Paper scaffold and migration commands maintain this exact
+version entry in `pnpm-workspace.yaml` so an immediately published, verified
+runtime can refresh the lockfile without weakening the policy for other
+packages.
 
 ## Repository Integration