@kungfu-tech/buildchain 3.0.4-alpha.3 → 3.0.4-alpha.5

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.3",
+    "version": "3.0.4-alpha.5",
     "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:11df0f88b1127261232e6c0f641aac4fbdc7bb17be0064a7571b38c06f070390"
     },
     {
       "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:e26656998e22ec27f96588959230bc97f9cc9ce8ecbd3a60ba639f4343aec88c"
     },
     {
       "contractVersion": 1,
@@ -3533,5 +3533,5 @@
     }
   ],
   "compatibilityDigest": "sha256:3bbcaf835844260ed98414d3bd176667245d12131e13fc748e4c2fae12399691",
-  "contractDigest": "sha256:3f17015215af1c964187e535ffd1b332ddc54808198104703397c5a7bd908fbd"
+  "contractDigest": "sha256:9e568e25e58803f8c592d1f2330ab1952569f386e280be581d90814df5642604"
 }