#selfdoc assembly

Manage the unified multi-project documentation assembly and deployment

#assembly init

Create and initialize the assembly GitHub repository with workflow and configuration files. Creates a private GitHub repo, pushes initial files via the Contents API, creates a Cloudflare Pages project if credentials are available, and sets GitHub secrets for deployment authentication.

Effect: mutating · consequential (prompts before running; --approve-consequential skips)

#Grants

#assembly push

Dispatch a GitHub Actions workflow to rebuild this project in the documentation assembly. Detects the source repository, resolves the latest git tag as the version reference, and sends a repository dispatch event to the assembly repo with the project slug, version, and commit SHA.

Effect: mutating

#Grants

#assembly status

Show the status of recent assembly build workflow runs on GitHub. Queries the assembly repository for recent workflow runs using the GitHub CLI and displays their status, conclusion, and timing information for monitoring deployment progress.

Effect: read_only

#assembly rebuild

Dispatch rebuild workflows for every project registered in the assembly. Fetches the projects.json manifest from the assembly repository, then sends a separate GitHub Actions repository dispatch event for each registered project to trigger a full documentation rebuild.

Effect: mutating

#Grants

#assembly retire

Retire a project from the unified assembly: remove its [[project]] block from the roster and, in the same commit, delete its whole site subtree, all of its manifests and its membership record, then dispatch a shared-only rebuild so the listing, feed, sitemap and search index stop naming it.

Effect: mutating · consequential (prompts before running; --approve-consequential skips)

#Flags

#Grants

#assembly redirects

Generate a Cloudflare Pages _redirects file for this project that redirects standalone documentation URLs to the corresponding paths on the unified assembly site. Requires a project slug and assembly base URL as inputs, prints the redirect rules to stdout.

Effect: read_only

#Flags

#assembly generate-shared

Generate the shared cross-project elements for the assembled documentation site. Reads per-project manifest JSON files, merges post overlays, and produces a homepage, blog index, navigation JSON, RSS feed, XML sitemap, robots.txt, a site-wide llms.txt linking to each project's own, a root 404 page, a security headers file and the redirect worker in the site output directory.

Effect: mutating

#Flags

#assembly integrate

Integrate one dispatched project into the assembly repository checkout and push the result. Builds the cloned source project, replaces its subtree under site/, refreshes its manifest and membership record, regenerates the shared cross-project elements, rebuilds the search index, then commits and pushes with a re-sync retry loop so concurrent deploys converge instead of clobbering each other. This is the whole body of the generated deploy workflow.

Effect: mutating

Dry run: not supported — 'assembly integrate' cannot be previewed: every step after the first reads what the step before it wrote -- the shared generator reads the manifests the graft just copied, the search index reads the pages it just wrote, and the commit reads the tree all of them produced. A recorded run writes none of that, so the preview would stop at the first effect and misrepresent everything after it. To see what an integration would produce, use 'assembly preview'.

#Flags

#Grants

#assembly verify

Assert every property a built assembly tree has to have before it is deployed: that the roster, the site subtrees and the manifests name the same projects, that each manifest's pages and posts were actually emitted, that the shared cross-project artifacts exist and parse, that every internal reference, sitemap entry, feed link and cross-project link resolves, that every page has a title and a canonical, and that no unresolved directive or per-project routing file survived. The deploy runs this itself before it pushes; this command is how you run the same assertions by hand against a checkout.

Effect: read_only

#Flags

#assembly preview

Assemble every named local checkout into a preview tree and serve it on loopback. Builds each project with the toolchain running this command, grafts the output exactly as the deploy does -- the home project at the site root, everybody else under their slug -- writes the roster, membership record and manifests the assembly keeps, generates the shared cross-project files and the site chrome, rebuilds the search index, runs the real pre-deploy verification and prints its report, then serves the result with a working 404. Nothing leaves the machine and nothing is published: this is the look-before-you-ship step.

Effect: mutating

Dry run: not supported — 'assembly preview' exists to produce output you look at: a built site tree and a server over it. A recorded run would write no tree, and every step after the build reads what the step before it wrote -- the graft reads the build, the shared generator reads the grafted manifests, the index and the verification read the pages. Run it without --dry-run; it publishes nothing.

#Flags

#assembly sync-workflow

Regenerate the assembly repository's deploy workflow from this project's configuration and push it. The deployed workflow is a generated artifact like any other: without this it stays frozen at whatever the template said when 'assembly init' ran. Pushes only when the content actually differs.

Effect: mutating

#Flags

#Grants