docs: add uf setup / uf init lifecycle section to Common Workflows

content/docs/getting-started/common-workflows.md

@@ -58,6 +58,32 @@ See also: [From Spec to Demo in One Command](/blog/unleash-in-practice/) — a n
 | 7    | **Return to Main**          | `git checkout main && git pull`.                                                    |
 | 8    | **Summary**                 | Displays completion report: branch, commit, PR, checks, status.                     |
 
+### Structured PR Descriptions
+
+When `/finale` creates a PR, it generates a structured body with these sections:
+
+- **Summary** — what the change does and why, derived from the branch's commit history and spec artifacts
+- **How to Test** — concrete steps a reviewer can follow to verify the change
+- **How to Demo** — how to demonstrate the feature to stakeholders
+- **Key Files Changed** — the most important files with brief descriptions of what changed in each
+
+Each section contains substantive content. For trivial changes, `/finale` writes brief notes rather than fabricating detail to fill the template.
+
+If unresolved findings from `/review-council` exist, `/finale` adds a **Known Issues** section listing them. This section is omitted when no review was run or all findings were resolved.
+
+The PR body ends with an attribution footer: `This PR was generated by /finale (AI-assisted).`
+
+### PR Template Detection
+
+If the repository contains a PR template (`.github/PULL_REQUEST_TEMPLATE.md`), `/finale` detects it and maps its generated sections to the template's headings using case-insensitive matching. When a template heading matches a generated section (e.g., a template heading containing "summary" maps to the Summary section), `/finale` fills in that section. Unmatched template sections are preserved as-is. If no template is found, `/finale` uses its default section format.
+
+### AI Attribution
+
+`/finale` adds AI attribution in two places:
+
+- **Commit message** — an `Assisted-by: <model>` [git trailer](https://git-scm.com/docs/git-interpret-trailers) and a `Generated with AI assistance (<model>)` footer line are appended to the commit message. The model name is a cleaned version of the model identifier (provider prefixes, routing suffixes, and version digits are stripped). The user can edit or remove the attribution during the commit message approval step.
+- **PR body** — an attribution footer appears as the last line of the PR description.
+
 ### Guardrails
 
 - Never runs on `main`
@@ -68,23 +94,6 @@ See also: [From Spec to Demo in One Command](/blog/unleash-in-practice/) — a n
 - Uses `--body-file` instead of inline `--body` to safely handle AI-generated content containing shell metacharacters
 - If any step fails, stops immediately with context and options
 
-### Structured PR Descriptions
-
-When creating a PR, `/uf.finale` generates a structured body with four sections:
-
-| Section              | Content                                                                 |
-| -------------------- | ----------------------------------------------------------------------- |
-| **Summary**          | What changed and why, derived from the diff and commit messages.        |
-| **How to Test**      | Steps to verify the changes locally.                                    |
-| **How to Demo**      | Steps to demonstrate the feature to stakeholders.                       |
-| **Key Files Changed**| List of modified files grouped by purpose.                              |
-
-**PR template detection**: If the repository contains `.github/PULL_REQUEST_TEMPLATE.md`, `/uf.finale` reads the template and maps its generated content into the template's sections instead of using the default structure.
-
-**Review council integration**: If a `/uf.review-council` report exists from a prior run, known issues are included in the PR body under a **Known Issues** section.
-
-**AI attribution**: Every PR created by `/uf.finale` includes an AI attribution footer in the PR body and an `AI-assisted-by: /uf.finale` git trailer in the commit metadata.
-
 ### Conflict Recovery
 
 When the push step (step 4) fails because the remote branch has diverged, `/uf.finale` enters conflict recovery mode and presents five options:
@@ -629,6 +638,90 @@ Then run the full autonomous pipeline:
 /uf.unleash
 ```
 
+## `uf setup` / `uf init` Lifecycle {#uf-setup-uf-init-lifecycle}
+
+The [Environment Setup](#environment-setup) section above covers the quick path: install, setup, verify, start. This section explains what `uf setup` and `uf init` actually do under the hood -- useful when troubleshooting, re-initializing an existing project, or understanding how the toolchain is assembled.
+
+### `uf setup`: Install Cascade
+
+`uf setup` installs the [four tool categories](#2-run-setup) listed in the Environment Setup section above, in order. As a final step, `uf init` runs automatically to scaffold the project.
+
+Setup detects your platform and adjusts the installation method accordingly:
+
+- **macOS with Homebrew**: installs via `brew install` where packages are available
+- **Fedora/RHEL with dnf**: installs via `dnf` for tools available in Fedora repos (e.g., Podman). Tools without native packages (Ollama, DevPod) fall back to their official curl installers with an interactive confirmation prompt
+- **Other platforms**: falls back to curl-based installers or version manager installs (goenv, nvm, fnm)
+
+Existing installations are detected and skipped. Use `--dry-run` to preview what would be installed without making changes.
+
+#### RPM Version Resolution (Fedora/RHEL)
+
+On dnf-based systems, `uf setup` resolves companion tool versions (Gaze, Replicator) independently. Rather than using the `uf` binary's own build-time version for all companion RPM URLs -- which could cause 404 errors when tool versions diverge -- each companion tool's latest release is resolved independently via `gh release view`. The resolved tag is validated for repository format, semver format, and length bounds.
+
+This means `gh` CLI must be installed before Gaze and Replicator on dnf-based systems. `uf setup` handles this ordering automatically, but if you see RPM 404 errors during manual installation, verify that `gh` is installed and has network access.
+
+### `uf init`: Project Scaffolding
+
+`uf init` is the final step of `uf setup`. It can also be run independently to initialize or re-initialize a project. The init process performs a 12-step scaffolding sequence:
+
+- Creates `.uf/config.yaml` for [workflow configuration](/docs/getting-started/common-workflows/#workflow-configuration)
+- Deploys agents, commands, convention packs, and templates into the project
+- Injects command-specific guardrails for Speckit and execution commands (4 variants: `speckit.implement`, `speckit.constitution`, `speckit.taskstoissues`, and general execution/utility)
+- Injects STOP HERE blocks for 6 spec-phase Speckit commands to enforce phase boundaries
+- Manages scaffold comment deduplication on re-runs to prevent duplicate injections
+- Cleans up legacy `unbound/packs/` directories from older versions
+- Performs sub-tool initialization (see below)
+
+Init is idempotent -- running it multiple times on the same project is safe. Branch enforcement and guardrail injection are split into independent checks, so partial re-runs complete correctly.
+
+### Sub-tool Initialization
+
+After scaffolding, `uf init` initializes companion tools concurrently. Five sub-tools -- Dewey, Gaze, Replicator, Specify, and OpenSpec -- are initialized in parallel via independent goroutines, reducing wall-clock time from ~90-120 seconds (sequential) to ~30-60 seconds.
+
+Sub-tools are divided into two groups:
+
+| Group | Tools | Notes |
+| ----- | ----- | ----- |
+| **Group A** | Dewey | Handles indexing and embedding generation. Receives `--no-embeddings` during init to avoid blocking. |
+| **Group B** | Specify, Replicator, OpenSpec, Gaze | Standard initialization with no special flags. |
+
+Dewey indexing no longer blocks other tool initialization. When Dewey is available, `uf init` runs `dewey init` + `dewey index --no-embeddings`. For full embedding generation, run `dewey index` separately after init completes.
+
+### Re-initialization (`--force`)
+
+`uf init --force` re-initializes all sub-tools across both Group A and Group B. This is useful when a tool's configuration has become corrupted, or after upgrading `uf` to pick up new init steps.
+
+Without `--force`, init only initializes tools that have not been initialized before. With `--force`:
+
+- All sub-tools are re-initialized regardless of current state
+- Tools that support `--force` receive the flag via their CLI
+- The init summary shows "re-initialized" vs. "initialized" for each tool to distinguish fresh vs. forced initialization
+
+Prior to v0.16.0, `--force` only re-initialized Group A (Dewey), silently skipping Group B tools. This was fixed so that `--force` now covers all sub-tools.
+
+### Guardrail Injection
+
+`uf init` injects command-specific guardrails into your project's agent configuration. There are four guardrail variants, each tailored to a different command category:
+
+- **`speckit.implement`** -- guardrails for the implementation phase
+- **`speckit.constitution`** -- guardrails for constitution management
+- **`speckit.taskstoissues`** -- guardrails for task-to-issue conversion
+- **Execution/utility** -- guardrails for general execution commands
+
+On re-runs, `uf init` self-corrects: correctness markers in the injected content allow init to detect outdated guardrails and replace them with the current version. This means upgrading `uf` and running `uf init` automatically updates your project's guardrails without manual intervention.
+
+### Stale Command Warnings
+
+After the `uf.*` namespace migration, running `uf init` on an existing project scans agent markdown files for references to old-name commands (the pre-`uf.*` namespace). If stale references are found, init emits warnings with actionable output identifying which files contain outdated command names. Update the flagged files to use the current `uf.*` namespace.
+
+### Troubleshooting
+
+**Dewey indexing hangs on `uf init --force`**: The `--force` flag passes `--no-embeddings` to Dewey's index command, so Dewey should not trigger full embedding generation during init. If Dewey appears to hang, it may be performing the initial workspace indexing on a large repository (~2300+ pages). Wait for it to complete, or cancel and run `dewey index` separately with `--no-embeddings` to skip the embedding generation pass. For full embedding generation (required for semantic search), run `dewey index` independently after init completes -- this runs Ollama with the Granite embedding model and can take several minutes depending on workspace size.
+
+**Stale command references after upgrade**: After upgrading `uf`, run `uf init` to trigger the stale command reference scan. If warnings appear, update the referenced files to use the `uf.*` namespace. The warning output identifies exact file paths and the old command names found.
+
+**RPM 404 errors on Fedora/RHEL**: If `uf setup` fails to download companion tool RPMs, verify that `gh` CLI is installed and has network access. Each companion tool's version is resolved independently via `gh release view`, so a missing or unauthenticated `gh` CLI will cause resolution failures. Run `gh auth status` to check authentication, and `gh release view --repo unbound-force/<tool>` to test version resolution manually.
+
 ## Next Steps
 
 - [Developer Guide](/docs/getting-started/developer/) -- Daily workflow, Speckit, Replicator, and Cobalt-Crush

content/docs/getting-started/developer.md

@@ -18,7 +18,7 @@ brew install unbound-force/tap/unbound-force
 uf setup
 ```
 
-`uf setup` detects your existing version managers (goenv, nvm, fnm, Homebrew) and installs through them:
+`uf setup` detects your existing version managers (goenv, nvm, fnm, Homebrew) and installs through them. For a detailed breakdown of what setup and init do under the hood, see [uf setup / uf init Lifecycle](/docs/getting-started/common-workflows/#uf-setup-uf-init-lifecycle).
 
 - **Core tools** -- OpenCode (AI coding environment), Gaze (quality analysis), Mx F (manager hero), GitHub CLI
 - **Development tools** -- Node.js, OpenSpec CLI, Replicator (multi-agent coordination)

content/docs/getting-started/quick-start.md

@@ -26,7 +26,7 @@ On **Fedora/RHEL** without Homebrew, install `uf` from the RPM package, then run
 - **Knowledge layer** -- Ollama (local model runtime), Dewey (semantic search), IBM Granite embedding model
 - **Project scaffolding** -- agents, commands, convention packs, templates, workflow configuration, and `.gitignore` management via `uf init`
 
-Setup detects your platform and version managers (goenv, nvm, fnm, Homebrew, dnf) and installs through them. Use `--dry-run` to preview what would be installed without making changes.
+Setup detects your platform and version managers (goenv, nvm, fnm, Homebrew, dnf) and installs through them. Use `--dry-run` to preview what would be installed without making changes. For a detailed breakdown of what setup and init do under the hood, see [uf setup / uf init Lifecycle](/docs/getting-started/common-workflows/#uf-setup-uf-init-lifecycle).
 
 ## Verify
 

openspec/changes/uf-init-setup-docs/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: unbound-force
+created: 2026-08-21

openspec/changes/uf-init-setup-docs/design.md

@@ -0,0 +1,55 @@
+## Context
+
+The website currently documents `uf setup` and `uf init` in fragmented mentions across Quick Start, Developer Guide, and Common Workflows. Users can figure out how to run the commands but lack understanding of what happens inside -- the 12-step init process, sub-tool concurrency, `--force` re-initialization groups, guardrail injection, and troubleshooting.
+
+Eight resolved GitHub issues (#203, #210, #211, #222, #223, #225, #236, #245) contain operational knowledge about these commands that exists only in issue/PR descriptions. The proposal calls for a dedicated lifecycle section on the Common Workflows page, plus cross-references from Quick Start and Developer Guide.
+
+Per the proposal's constitution alignment: this change is documentation-only (N/A for Autonomous Collaboration, Observable Quality, Testability; PASS for Composability First since it documents the composable nature of sub-tool initialization).
+
+## Goals / Non-Goals
+
+### Goals
+- Add a comprehensive `uf init` / `uf setup` lifecycle section to Common Workflows that explains what each command does, how sub-tool initialization works, `--force` behavior, and common issues.
+- Add cross-references from Quick Start and Developer Guide to the new section.
+- Source all technical details from resolved GitHub issues and existing documentation -- no fabrication.
+- Maintain the existing page structure and navigation (no new pages, no menu changes).
+
+### Non-Goals
+- CLI reference documentation (flags, exit codes, full option listing) -- that belongs in the reference section, not getting-started.
+- Documenting the internal Go implementation of `uf init` or `uf setup`.
+- Documenting `uf doctor` in more depth (already covered adequately in Quick Start and Developer Guide).
+- Creating a separate dedicated page -- the lifecycle section fits naturally within Common Workflows alongside the existing Environment Setup section.
+
+## Decisions
+
+### D1: Add section to Common Workflows rather than creating a new page
+
+**Rationale**: Common Workflows already has an "Environment Setup" section (lines 396-465) that covers Install CLI, Run Setup, Verify, and Start Working. The lifecycle section extends this existing content with deeper operational detail. A separate page would fragment the setup documentation further when the goal is consolidation. The Common Workflows page already serves as the "how things work end-to-end" reference.
+
+**Placement**: Insert the new lifecycle section immediately after the existing "Environment Setup" section and before "Next Steps". This keeps the learning progression: quick setup steps first, then detailed lifecycle for users who want to understand more.
+
+### D2: Organize by command (`uf setup` then `uf init`) rather than by feature
+
+**Rationale**: Users encounter `uf setup` first (it calls `uf init` as its final step). Organizing by command matches the user's mental model: "I ran setup, then init happened -- what did each do?" Feature-based organization (e.g., "guardrails", "sub-tools") would require users to already know the architecture.
+
+### D3: Include a troubleshooting subsection within the lifecycle section
+
+**Rationale**: The three most common issues (Dewey hang on `--force`, stale command references, RPM version resolution on Fedora) are directly caused by lifecycle behavior. Placing troubleshooting adjacent to the lifecycle explanation connects the problem to the cause. A separate troubleshooting page would lose this context.
+
+### D4: Cross-references use inline links, not callout boxes
+
+**Rationale**: Quick Start and Developer Guide already have dense content. A callout box ("Want to learn more about setup? See...") would add visual weight. An inline link within existing prose is less disruptive and follows the pattern already used on these pages.
+
+## Risks / Trade-offs
+
+### Common Workflows page length
+Adding ~150-200 lines to an already 465-line page. **Mitigation**: The page has `toc: true`, so the new section appears in the table of contents for direct navigation. The Doks theme handles long pages well with its sticky TOC sidebar.
+
+### Content sourced from issues may go stale
+Issue details reflect the state at PR merge time. Future changes to `uf init`/`uf setup` could make the documentation inaccurate. **Mitigation**: The documentation describes behavior at a conceptual level (e.g., "sub-tools initialize concurrently") rather than implementation details (e.g., "goroutines with errgroup"). This makes it more resilient to internal refactoring. The website documentation gate (AGENTS.md) requires a website issue when user-facing CLI behavior changes.
+
+### Fedora/RHEL details may not apply to most users
+`uf setup` RPM version resolution (#236) is platform-specific. **Mitigation**: Platform-specific details are in a clearly labeled subsection so macOS/Homebrew users can skip them.
+
+### Overlap with `init-setup-error-docs` OpenSpec change
+The sibling OpenSpec change `init-setup-error-docs` also modifies `content/docs/getting-started/developer.md`, adding error output notes to the "Sub-Tool Initialization" section. This change (task 2.2) adds a cross-reference link in the Prerequisites section, which is a different section of the same file. The two changes are complementary -- the lifecycle section in Common Workflows provides operational context that complements the error output notes in the Developer Guide. No content duplication or merge conflict is expected, but implementers should verify line numbers if the sibling change lands first.