Docs Site Bootstrap

Docs Site Bootstrap

Initializes a host repository's formal documentation foundation under the fixed root docs/site/. This file owns the entry, opt-in, idempotency, and conflict gates. Load _internal/INSTRUCTIONS.md only after every gate below passes.

Reader-Facing Writing Composition

For substantial reader-facing prose, co-load human-writing even on direct invocation; use the same context, not a later pass. This Skill retains evidence, facts, required structure, paths, gates, and verification. Skip code-, config-, schema-, lockfile-, and data-only output.

Mandatory Bootstrap Decision

Resolve the complete authoritative asset inventory before writing. If any target differs, report the full conflict list and offer exactly overwrite, explicit merge, or keep-existing for each conflict; do not partially apply the scaffold first. After a first committed bootstrap, classify deployment completeness and ask the integrated/independent/deferred decision. After every re-bootstrap, rerun the same evidence check and report drift even when the asset copy itself is zero-diff.

The decision explicitly records the confirmed host repository, fixed docs/site/ root, and user opt-in for the complete scaffold and manifest. A conflict remains blocked until the user chooses one of the three actions for every listed path; never record kept-as-is before that choice.

Entry Credentials

Require both of these credentials before inspecting or writing bootstrap targets:

• the user explicitly requests initialization or creation of the formal documentation site; and
• the target host repository path is confirmed.

An explicit bootstrap request and a confirmed repository path are the specialist entry basis. If either is missing, stop before writing and return to docs-agent or pm-agent for clarification. The generated root is always docs/site/; do not silently adapt the scaffold to another root.

Authoritative Opt-In Gate

Bootstrap is opt-in. Do not trigger it because another workflow merely discovers that docs/site/ is absent. In particular, formal-docs-sync and docs-audit may explain the missing foundation and suggest this specialist, but they must not initialize it or create a partial scaffold on the user's behalf.

Before writing, restate the confirmed repository and docs/site/ target, then confirm that the request covers the generated manifest and the complete scaffold described in _internal/INSTRUCTIONS.md.

Idempotency and Conflict Gate

Build the complete target inventory and establish docs/site/.meta/bootstrap-manifest.json before applying asset files. For every target path:

• create it when it does not exist and record created;
• skip it when its content is byte-identical to the corresponding asset and record skipped-identical;
• if it differs, report it in the complete conflict list and stop before overwriting that file; never preserve a conflict silently.

For each conflict, require the user to choose overwrite, explicit merge, or keep the existing file. A keep decision records kept-as-is in the manifest; later runs must skip asset-equality enforcement for that exact path. An existing kept-as-is record is not permission to overwrite or normalize the file.

Do not partially overwrite conflicting files before the user resolves them. Non-conflicting new files may be generated within the already confirmed bootstrap scope. Repeated execution must produce zero content changes when the assets and manifest decisions are unchanged, and must never reset an existing change map, release metadata, or formal documentation page.

Execution Source

The authoritative path inventory, manifest state transitions, write order, asset-to-host mapping, and read-back checks live in _internal/INSTRUCTIONS.md. Static host output lives under assets/docs/site/** with the same relative paths as host docs/site/**. Load the internal entry only after the entry and opt-in gates pass, then copy asset bytes exactly except for explicit user-approved conflict resolution; do not fetch scaffold files from another repository.

Output

After a first complete bootstrap, run the shared read-only documentation-site deployment completeness check only after the durable bootstrap changes are committed and the user confirms that commit. After every completed re-bootstrap, including an idempotent run, rerun the check for drift. Present the shared stable result and require one of its three user decisions: integrate all build variants, retain confirmed independent hosting, or defer with an explicit blocker. Bootstrap completion does not authorize commit, push, image publication, or deployment.

Report:

• confirmed host repository and generated root
• created and identical-skipped paths
• kept-as-is paths and the user decision that authorized each one
• unresolved conflicts and available resolution choices
• manifest path and read-back result
• whether a repeat run would be zero-diff
• deployment-completeness status, evidence, discovered build variants, user decision, or the pending post-commit trigger
• recommended handoff to formal-docs-sync, then wait for confirmation

At closeout, follow the safety-net behavior in the plugin-local generated ../docs-agent/_internal/_generated/shared-contracts/closeout-contract.md.