@kungfu-tech/buildchain 3.0.4-alpha.4 → 3.0.4-alpha.6

package/AGENTS.md

@@ -6,9 +6,14 @@ restating them.
 
 ## Are you using Buildchain, or building it?
 
-- **Using Buildchain** - initialize a repository, call a reusable workflow, run
-  a release dry-run, or inspect the release model: start at the documentation
-  map, [`docs/MAP.md`](docs/MAP.md).
+- **Adopting Buildchain for the first time** - follow the 15-30 minute
+  [`Golden Path`](docs/getting-started.md).
+- **Looking up a CLI command** - use the generated
+  [`CLI Reference`](docs/cli-reference.md).
+- **Writing Node build automation** - use the generated
+  [`Node API Reference`](docs/node-api-reference.md).
+- **Exploring advanced workflows, release governance, or product
+  capabilities** - start at the [`Documentation Map`](docs/MAP.md).
 - **Building or contributing to this repo** - read the rest of this file, then
   [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
@@ -74,8 +79,9 @@ pnpm install --frozen-lockfile
 pnpm run check
 ```
 
-`pnpm run check` validates inventory data, lints root workflows, runs unit tests,
-and rebuilds every action bundle.
+`pnpm run check` validates inventory data, generated public references and site
+bundle drift, lints root workflows, runs unit tests, and rebuilds every action
+bundle.
 
 Before broad maintenance or consolidation work, read the current engineering
 handoff in
@@ -109,6 +115,9 @@ handoff in
 - Do not build or document official release integrations that bypass provider
   protections, hide credential boundaries, or forge release evidence.
 - Keep generated action bundles in sync with source changes.
+- When public documentation, CLI usage authority, or package exports change,
+  follow the [Site Bundle Contract generation steps](docs/site-bundle-contract.md#generation)
+  and commit the updated generated references and `dist/site/` facts.
 - Keep documentation in sync with behavior, especially release governance and
   reusable workflow contracts.
 - [`docs/MAP.md`](docs/MAP.md) and [`CONTRIBUTING.md`](CONTRIBUTING.md) are the

package/README.md

@@ -25,6 +25,20 @@ its existing CI.
 
 The same mechanism releases Buildchain itself.
 
+## Choose Your Path
+
+| You are... | Start here | You will get... |
+| --- | --- | --- |
+| adopting Buildchain for the first time | [Golden Path](docs/getting-started.md) | an exact install, project declaration, validated config, reusable workflow, release dry-run, and Passport inspection |
+| looking up a CLI command | [Generated CLI Reference](docs/cli-reference.md) | governed syntax, options, aliases, and side-effect-free help paths |
+| writing JavaScript automation | [Generated Node API Reference](docs/node-api-reference.md) | every public subpath and symbol with source-derived signatures and behavior boundaries |
+| operating an advanced build or release | [Documentation Map](docs/MAP.md) | capability-, intent-, and maturity-based navigation to normative contracts |
+
+The Golden Path is the beginner lane. Advanced workflow, signing, publishing,
+and governance manuals remain separate so a first-time consumer does not need
+to understand the entire release control plane before reaching a valid local
+configuration.
+
 ## Where Buildchain sits in the Agent Supply Chain
 
 Buildchain binds a product's declarations to the exact source cut, build,
@@ -48,6 +62,10 @@ or protocol evidence through the repository issue tracker.
 
 ## Install and Verify
 
+New repository adopters should follow the [15–30 minute Golden Path](docs/getting-started.md).
+The commands below are the shorter verification-only route for an existing
+consumer.
+
 For v3, use the published npm package and verify the release passport before
 trusting release evidence:
 

package/bin/buildchain.mjs

@@ -14,6 +14,7 @@ import { runPublicationPackageCli } from "../scripts/publication-package.mjs";
 import { runPublicationReproducibilityCli } from "../scripts/publication-reproducibility.mjs";
 import { runPaperCli } from "../scripts/paper.mjs";
 import { BUILDCHAIN_USAGE } from "../scripts/buildchain-cli-help.mjs";
+import { formatCliHelp } from "../scripts/public-reference.mjs";
 import { validateBuildchainConfig } from "../packages/core/buildchain-config.js";
 import { detectPackageManager } from "../packages/core/package-manager.js";
 import {
@@ -1224,7 +1225,7 @@ async function runProcessTreeSample(sampleArgs = []) {
 }
 
 async function handleHelpCommand(args) {
-    process.stdout.write(BUILDCHAIN_USAGE);
+    process.stdout.write(formatCliHelp({ usageText: BUILDCHAIN_USAGE, pathParts: args }));
     return;
 
 }
@@ -1732,6 +1733,14 @@ const BUILDCHAIN_COMMAND_HANDLERS = Object.freeze({
 });
 
 async function main(argv = process.argv.slice(2)) {
+  const helpIndex = argv.findIndex((entry) => entry === "--help" || entry === "-h");
+  if (helpIndex >= 0) {
+    process.stdout.write(formatCliHelp({
+      usageText: BUILDCHAIN_USAGE,
+      pathParts: argv.slice(0, helpIndex),
+    }));
+    return;
+  }
   const [command = "help", ...args] = argv;
   return dispatchRegisteredCommand({
     command,

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "3.0.4-alpha.4",
+    "version": "3.0.4-alpha.6",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v3",
@@ -619,7 +619,7 @@
         "README badge block checks and writes are generated from machine-readable repository facts"
       ],
       "breakingDigest": "sha256:90a73892b2d6c214048448d5f45df75639bdf7b7e8fefd9c596e04b087407bcc",
-      "auditDigest": "sha256:2011241d29b5636c751a0a03c5be0fd43e90e7f5d246f651975cab2d7ebcead3"
+      "auditDigest": "sha256:f3be0e8ce65d5860d1ad808990f78a1fd48c18207a9aacf1ba63fd0d0e51be40"
     },
     {
       "contractVersion": 1,
@@ -709,7 +709,7 @@
         "manual entries carry source file digests so downstream sites and agents can detect stale hand-written documentation"
       ],
       "breakingDigest": "sha256:7d0d2819e3a3e72989d9c57b5efe9d0bc0a79bc0f2c82a0c7b9d6c5a211a91f2",
-      "auditDigest": "sha256:e6948b309515f693f4a264500184bcf2670b025e8e5d45e0b999d305483bd3bd"
+      "auditDigest": "sha256:b8e1f1d16a1810807d3b5f8b82a06d146d53d8581d4a21969b44d6d2e91804e8"
     },
     {
       "contractVersion": 1,
@@ -731,7 +731,7 @@
         "agents can discover supported Node APIs without importing internal file paths"
       ],
       "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
-      "auditDigest": "sha256:b7862559002c267b6ab56df3e45cb15248e4179db9a04cd0963117c312a73069"
+      "auditDigest": "sha256:7c7ebec50b3a7f24cd0bbfbca70b55c950bcce54c24d9e354a5863d98b6169b4"
     },
     {
       "contractVersion": 1,
@@ -3533,5 +3533,5 @@
     }
   ],
   "compatibilityDigest": "sha256:3bbcaf835844260ed98414d3bd176667245d12131e13fc748e4c2fae12399691",
-  "contractDigest": "sha256:3400aed2a210ace06f1fe2cf2aaa654ff40cf0571214237d0bc9b93d4318fb90"
+  "contractDigest": "sha256:ba6f71012f1d2a796ff2f621bbfabc3cee2b95902dcdf662d1dd60a205b8baf7"
 }