Skip to content

merge: sync docs-v2-dev into docs-v2#860

Merged
DeveloperAlly merged 1089 commits intodocs-v2from
merge/docs-v2-dev-into-docs-v2-20260407
Apr 7, 2026
Merged

merge: sync docs-v2-dev into docs-v2#860
DeveloperAlly merged 1089 commits intodocs-v2from
merge/docs-v2-dev-into-docs-v2-20260407

Conversation

@DeveloperAlly
Copy link
Copy Markdown
Collaborator

@DeveloperAlly DeveloperAlly commented Apr 6, 2026

Description

Syncs docs-v2-dev into docs-v2, treating docs-v2-dev as the source of truth for docs content, navigation shape, scripts, workflows, cleanup, and docs.json. Fixes two GitHub Actions workflow correctness issues in generate-action-docs.yml identified during review.

Scope

  • .github/workspace/actions-library/generators/maintenance/generate-action-docs.yml — fix on.push.branches literal value and guard inputs.dry_run references
  • v2/** — content and navigation alignment from docs-v2-dev
  • .github/workflows/** — workflow path updates, branch/trigger configuration
  • docs.json — navigation shape from docs-v2-dev
  • Repo governance artifacts: allowlist, agent rules, stale backups/locks

Out of scope: style-guide and copy-lint violations in existing docs-v2-dev content debt (tracked as follow-up).

Validation

  • Passed: node operations/scripts/validators/content/structure/lint-structure.js --check
  • Passed: node operations/scripts/validators/governance/compliance/check-agent-docs-freshness.js --json
  • Passed: node operations/tests/unit/docs-navigation.test.js
  • Passed: node operations/tests/unit/authoring-tools.test.js
  • Passed: node operations/tests/unit/mdx.test.js --staged
  • Passed: merge commit pre-commit hard gates
  • Inconclusive: node operations/tests/integration/mdx-component-runtime-smoke.js brought the scoped server up successfully but did not return a final harness result before manual stop
  • Failing on existing docs-v2-dev content debt: node operations/tests/run-pr-checks.js --base-ref docs-v2 reports large style/copy-policy failures across the branch diff, independent of merge-conflict resolution

Follow-up Tasks

  • Triage and fix the existing style-guide and copy-lint violations surfaced by PR-scope checks if this branch is expected to merge with a green CI lane.
  • Re-run the runtime smoke harness after investigating why the wrapper does not return after the scoped preview server is ready.

Type of Change

  • Bug fix (fixes an issue)
  • New content (adds new documentation)
  • Content update (improves existing content)
  • Style/formatting fix
  • Information architecture change
  • Other (merge integration + workflow correctness fixes)

Related to #

Changes Made

  • Treats docs-v2-dev as the source of truth and merges into docs-v2 via a clean integration worktree (merge commit 4282b5993).
  • Removes unauthorized base-side root directories (docs/, tests/) that violated the repo allowlist.
  • Removes tracked machine/local artifacts including .claude session state, .codex/locks-local JSON, and docs.json.bak.
  • Updates scoped preview navigation configs so their /redirect surface matches the committed docs.json state.
  • Removes the obsolete v2/resources/redirect Resource HUB anchor contract and aligns the public Resources tab with the current non-anchor tab model.
  • Fixes on.push.branches in generate-action-docs.yml — replaces the unsupported context expression ${{ vars.DEPLOY_BRANCH }} with the literal branch name docs-v2.
  • Fixes unsafe inputs.dry_run references in generate-action-docs.yml — computes a DRY_RUN env var once as ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || false }} and replaces all three inputs.dry_run usages with $DRY_RUN (shell) and env.DRY_RUN (expression context), so push-triggered runs no longer fail when inputs is undefined.

Testing

  • Tested locally with npm run dev
  • Verified all links work
  • Checked formatting and style
  • Reviewed against style guides
  • Screenshots (if UI changes)

Screenshots (if applicable)

N/A

Checklist

  • My changes follow the style guides
  • I've reviewed the Component Library for available components
  • I've updated related pages if needed
  • I've checked for broken links
  • My changes are clear and easy to understand
  • I've tested locally
  • I've added/updated keywords and metadata if needed

Additional Notes

The two generate-action-docs.yml fixes ensure the workflow loads and triggers correctly on push events: the on.push.branches field now uses a literal branch name (required by GitHub Actions), and all inputs.dry_run references are guarded so they safely default to false when inputs is not available (i.e., on non-workflow_dispatch triggers).

Governance Approval

Not required for this PR.

Copy Governance Gate - L5

Complete before requesting review. Every item must be checked or the PR is not ready.

Auto-checked by CI (lint-copy.js + lint-structure.js)

  • No Tier 1 banned words or phrases
  • No unresolved {/* REVIEW: */} flags in rendered content
  • No non-USD currency outside declared regional scope
  • No empty cells in decision tables
  • pageType, audience, lastVerified present in frontmatter

Human review required

Sequence (L2)

  • Page opens with operator outcome - value kept, no conditionals
  • Majority operator path is featured before variants
  • Introduced paths are developed on-page or linked

Completeness (L3)

  • Decision aids (tables, matrices, flowcharts) are complete - no placeholders
  • Every warning or consequence is followed by a prevention action and link
  • Primary actions and URLs appear in body copy (not only in accordions)

Tone (L4)

  • No sentence ends on a hedge, disclaimer, or restatement
  • No section ends with a Note that apologises rather than forward-points

Brief compliance

  • L0 (Q1-Q4) was completed before drafting
  • L1 persona mapping table was completed before drafting

If any structural item fails: fix before requesting review. Do not ask a reviewer to identify the issue.

If the same section fails review twice: do not attempt a third fix. Escalate to the documentation lead for L6 diagnostic.

DeveloperAlly and others added 30 commits March 20, 2026 18:49
…s flag

- component-governance-utils: add getChangedMdxFilesSince(ref) and files
  option on scanMDXImports for incremental MDX scans
- scan-component-imports: add --since <commit> incremental mode; narrows
  MDX scan to changed files while keeping full component inventory
- audit-component-usage: remove execSync/child_process; use getComponentFiles,
  extractExports, scanMDXImports from shared utils; fix REPORT_PATH to use
  REPO_ROOT instead of brittle __dirname traversal
- lint-structure: add --files path1,path2,... flag; priority order is
  LINT_FILE_LIST > --files > --changed-files > positional arg

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ent branch

lint-structure.js is a content validator, not component governance tooling.
The --files flag addition belongs on docs-v2-dev directly.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
… restructure

- Fix 136 stale paths in script-classifications.json (111 remapped to
  new taxonomy locations, 8 remapped to x-archive, 17 deleted entries)
- Add 21 missing classification rows for new and split scripts
- Regenerate scripts-catalog.mdx, pages-catalog.mdx, and all
  group script-index.md files
- Fix stale spawn path in export-portable-skills.test.js
- Fix stale component path in authoring-tools.test.js (quote.jsx moved)
- Fix stale generate-ai-skills-indexes.js path in ai-tools-registry.json
- Fix 4 stale artifact paths in ai-tools-registry.json (files moved
  to _workspace/ in latest docs-v2-dev merge)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add missing @param className/style to all 22 component exports that
destructure those props without JSDoc entries. Fix EmbedMarkdown JSDoc
detection (archived comment was breaking block parse). Add @SubNiche
to MermaidColours. Fix OPTIONAL_GOVERNANCE_FIELDS not being mapped onto
parsed JSDoc object (causing false @Datasource warnings on all integrators).
0 violations on generate-component-registry.js --strict.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Replace __dirname traversal with process.cwd()/git rev-parse REPO_ROOT
  in 6 scripts: audit-component-usage, terminology-search, generate-glossary,
  generate-seo, test-v2-pages, lint-copy
- Extract magic string 'tools/scripts' to SCRIPTS_ROOT constant in
  script-footprint-and-usage-audit.js
- Extract buried path constant RETENTION_POLICY_PATH to config block
  in quarantine-manager.js
- Extract hardcoded audit-script-inventory.js path to AUDIT_SCRIPT
  constant in repair-script-inventory.js
- Extract V2_ROOT constant in generate-seo.js; replace all /v2/ magic
  strings with template literals
- Add Task 13 (script docs consolidation analysis) to plan.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Analysis of all current script documentation surfaces, problems
identified (schema drift, duplication, no single source of truth),
and proposed architecture for Task 13 execution.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…solidation recommendations

54 surfaces audited across 6 categories. Proposes script-registry.json as
single source of truth, script-governance.mdx on nav, and JSON→MDX
aggregation pattern for both scripts and components.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
TL;DR: one JSON registry per domain → everything generated from it,
plus one spec page on the nav. Includes decisions needed, execution
order, and blockers (27 mistyped @type values, missing component registry).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Architecture decision report and full 54-surface audit for script
documentation consolidation. One JSON registry, one spec on nav.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
docs-guide-sot.test.js and run-all.js still referenced old flat script
paths under tools/scripts/. Update all to match Task 9 reorganisation:
  generate-docs-guide-*.js  → generators/governance/catalogs/
  generate-ui-templates.js  → generators/components/library/
  audit-component-usage.js  → audits/components/documentation/
  generate-component-docs.js → generators/components/documentation/

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Moves the extension reference page to docs-guide/tooling/ and registers
it in the Tooling navigation group in docs.json. Adds a Future Features
section documenting Mermaid lazy-loading, component promotion, syntax
highlighting, scroll sync, and hot-reload improvements.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…lan, @type fix

- plan.md: strike through completed tasks 1, 11, 11a-f, 12, 12c, 13.1-13.4
- doc-recommendation.md: add MDX-in-MDX opportunity, spec accuracy section,
  locale mirrors (3 mirrors confirmed: cn/es/fr), Q4+Q5 decisions, correct
  @type count from 27→1 remaining (fixed), update execution order
- task-13-subplan.md: full execution sub-plan for T13 with steps, risks,
  file list, and Q1-Q5 approval table
- update-jsdoc-headers.js: add proper 11-tag JSDoc header with @type remediator

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Mermaid.js (2.45 MB) is now only injected when the page contains at
least one mermaid segment. Pages without diagrams skip the bundle.

Component hot-reload: saving any .jsx file in the workspace now
triggers a re-render of all open preview panels.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Task 13b: auto-generated file governance — extend banner enforcement
  to non-MDX files (.md indexes, .json registries) + AI-explicit callout
- Task 13c: tasks/ → workspace/ rename before Task 14; sub-plan created
  at task-13c-workspace-rename-subplan.md with full audit, risk register,
  step-by-step execution
- Task 13d: lpd-cli audit + governance + docs recommendations
- Execution summary table updated with 13, 13b, 13c, 13d

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- tasks/plan/active/index.md: comprehensive index of all 9 active governance
  plans + content frameworks + published policies + frameworks, with per-section
  summaries and file tables
- autogenerated-file-governance.md: Task 13b full implementation recommendation
  — HTML comments for .md, _generated key for .json, AI-AGENT line in MDX
  hidden banner, extend generated-artifacts.json + enforce-generated-file-banners.js

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add component-docs.md: Task 10 pre-flight architecture audit covering
  all 12 documentation surfaces, taxonomy divergence, 14 vs 7 field
  schema problem, and recommended SOT architecture
- Refresh component-usage-map.json from latest scan post-Task-8 fixes

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
DeveloperAlly and others added 9 commits April 7, 2026 18:44
- Fix fabricated import paths across 59 files
- Restore SearchTable.jsx component imports
- Remove unauthorised CDN asset contract system
- Restore inline CDN URLs in 8 consumer files
- Fix duplicate frontmatter keys in 6 About pages
- Fix multi-view-layout.mdx broken JSX comment syntax
- Fix 5 gateway custom composable imports
- Remove moved x-deprecated files from docs.json nav

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
allow-deletions: true
allow-deletions: true

# Conflicts:
#	operations/reports/health/page-imports/page-imports-audit.json
#	operations/reports/health/page-imports/page-imports-audit.md
#	snippets/templates/pages/gold-standard/multi-view-layout.mdx
#	v2/about/concepts/core-concepts.mdx
#	v2/about/network/overview.mdx
#	v2/about/protocol/design-philosophy.mdx
#	v2/about/protocol/economics.mdx
#	v2/about/resources/reference/technical-roadmap.mdx
#	v2/gateways/custom/views/quickstart/docker/dockerOffChainTab.mdx
#	v2/gateways/custom/views/quickstart/docker/dockerOnChainTab.mdx
#	v2/gateways/quickstart/views/docker/dockerOffChainTab.mdx
#	v2/gateways/quickstart/views/docker/dockerOnChainTab.mdx
#	v2/home/mission-control.mdx
#	workspace/plan/active/_MY_PROCESS/00_AUDIENCE-JOURNEY/ALL-CURRENT-INFORMATION/RESEARCH/ABOUT/claude-web-output/core-concepts.mdx
#	workspace/plan/active/_MY_PROCESS/00_AUDIENCE-JOURNEY/ALL-CURRENT-INFORMATION/RESEARCH/ABOUT/claude-web-output/design-philosophy.mdx
#	workspace/plan/active/_MY_PROCESS/00_AUDIENCE-JOURNEY/ALL-CURRENT-INFORMATION/RESEARCH/ABOUT/claude-web-output/economics.mdx
#	workspace/plan/active/_MY_PROCESS/00_AUDIENCE-JOURNEY/ALL-CURRENT-INFORMATION/RESEARCH/ABOUT/claude-web-output/economics2.mdx
#	workspace/plan/active/_MY_PROCESS/00_AUDIENCE-JOURNEY/ALL-CURRENT-INFORMATION/RESEARCH/ABOUT/claude-web-output/network-overview.mdx
#	workspace/plan/active/_MY_PROCESS/00_AUDIENCE-JOURNEY/ALL-CURRENT-INFORMATION/RESEARCH/ABOUT/claude-web-output/technical-roadmap.mdx
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Fix fabricated import paths across all files
- Remove unauthorised CDN asset contract system
- Restore SearchTable.jsx component imports
- Fix gateway custom composable imports
- Remove stale docs.json nav refs
- Restore the-lott-hero-video.mp4 from merge base

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
allow-deletions: true
allow-deletions: true

# Conflicts:
#	docs.json
#	workspace/plan/active/_Project-Management_/completion-reports.md
#	workspace/thread-outputs/sessions/session-log.txt
@DeveloperAlly DeveloperAlly merged commit fc961f6 into docs-v2 Apr 7, 2026
5 of 14 checks passed
@DeveloperAlly DeveloperAlly deleted the merge/docs-v2-dev-into-docs-v2-20260407 branch April 7, 2026 11:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants