the-craftlab · jamesvillarrubia · Jun 20, 2026 · Jun 25, 2026
diff --git a/README.md b/README.md
@@ -21,11 +21,17 @@ Skip the debugging cycles. Generate battle-tested CI/CD workflows into your repo
 
 ---
 
-## 📚 Complete Documentation
+## 📚 Documentation
 
-**[Read the full documentation at pipecraft.thecraftlab.dev →](https://pipecraft.thecraftlab.dev)**
+**For users — [pipecraft.thecraftlab.dev →](https://pipecraft.thecraftlab.dev)**
 
-The documentation site includes comprehensive guides, real-world examples, configuration references, and troubleshooting help.
+The documentation site is the product manual: get-started + quickstart, guides (workflow generation, patterns, versioning, examples), reference (CLI, configuration, action modes), how-it-works, and help (troubleshooting, error reference, FAQ).
+
+**For contributors — develop Pipecraft itself:**
+
+- [CONTRIBUTING.md](./CONTRIBUTING.md) — setup, workflow, and how to contribute
+- [docs-dev/testing.md](./docs-dev/testing.md) — testing philosophy and how to run/write tests
+- [docs-dev/ast-operations.md](./docs-dev/ast-operations.md) — how the generator manipulates YAML (AST path operations)
 
 ---
 

diff --git a/docs/docs/ast-operations.md → docs-dev/ast-operations.md b/docs/docs/ast-operations.md → docs-dev/ast-operations.md
diff --git a/docs/docs/testing-guide.md → docs-dev/testing.md b/docs/docs/testing-guide.md → docs-dev/testing.md
diff --git a/docs/docs/cli-reference.md b/docs/docs/cli-reference.md
@@ -1,4 +1,4 @@
-# CLI Reference
+# Quickstart
 
 PipeCraft is a command-line tool that generates CI/CD workflows for your project. This guide covers the essential commands you'll use day-to-day.
 
@@ -27,23 +27,19 @@ cd your-project
 npx pipecraft init
 ```
 
-This launches an interactive setup that asks you about your project structure. It will ask questions like:
+By default `init` is **non-interactive**: it writes a starter `.pipecraftrc` using sensible defaults, which you can override with flags:
 
-- Which branches you want to use (develop, staging, main)
-- Which package manager you use (npm, yarn, or pnpm) - auto-detected from lockfiles
-- What domains exist in your codebase (api, web, etc.)
-- Which paths belong to each domain
-
-The init command automatically detects your package manager by checking for lockfiles:
+```bash
+npx pipecraft init --initial-branch develop --final-branch main --ci-provider github
+```
 
-- `pnpm-lock.yaml` → pnpm
-- `yarn.lock` → yarn
-- `package-lock.json` → npm
-- No lockfile → defaults to npm
+Prefer to be walked through it? Use the interactive wizard:
 
-You can confirm or override the detected package manager during the interactive prompts.
+```bash
+npx pipecraft init --interactive
+```
 
-Once complete, you'll have a `.pipecraftrc` file that contains your configuration (format can be JSON, YAML, or JavaScript).
+Once complete, you'll have a `.pipecraftrc` file you can edit to define your branch flow and domains (format can be JSON, YAML, or JavaScript). Domain change detection is path-based, so any project — including monorepos — is configured by pointing each domain at its file globs.
 
 ## Generating workflows
 
@@ -224,20 +220,28 @@ npx pipecraft init
 # 3. Generate workflows
 npx pipecraft generate
 
-# 5. Review the generated files
+# 4. Review the generated files
 ls -la .github/workflows/
 cat .github/workflows/pipeline.yml
 
-# 6. Commit the changes
+# 5. Commit the changes
 git add .github/ .pipecraftrc
 git commit -m "chore: add pipecraft workflows"
 git push
 
-# 7. Set up GitHub (requires a token)
-export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
+# 6. Create the branch flow (develop, staging, main, ...) on the remote
 pipecraft setup
+
+# 7. Configure GitHub Actions permissions (requires a token)
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
+pipecraft setup-github --apply
 ```
 
+Two distinct setup commands, both needed before promotions work:
+
+- **`pipecraft setup`** creates the branches in your `branchFlow` on the remote (e.g. `staging`, `production`). Promotion opens PRs into these branches, so they must exist first.
+- **`pipecraft setup-github`** configures the repository's Actions permissions (read/write, allow PR creation) so the version/tag/promote jobs can run.
+
 ## Configuration file
 
 PipeCraft looks for configuration in several places, in this order:
@@ -254,19 +258,26 @@ Most projects use `.pipecraftrc` because it's simple and can be either JSON or Y
 ```json
 {
   "ciProvider": "github",
+  "mergeStrategy": "fast-forward",
+  "requireConventionalCommits": true,
   "branchFlow": ["develop", "staging", "main"],
   "initialBranch": "develop",
   "finalBranch": "main",
+  "semver": {
+    "bumpRules": { "feat": "minor", "fix": "patch", "breaking": "major" }
+  },
   "domains": {
     "app": {
       "paths": ["src/**"],
-      "testable": true,
-      "deployable": true
+      "description": "Application code",
+      "prefixes": ["test", "deploy"]
     }
   }
 }
 ```
 
+`mergeStrategy`, `requireConventionalCommits`, and `semver` are required — `pipecraft validate` will tell you if any are missing. Use `prefixes` to choose which jobs a domain generates (e.g. `["test", "deploy"]`); the older `testable`/`deployable` flags are deprecated.
+
 This configuration tells PipeCraft to:
 
 - Generate GitHub Actions workflows

diff --git a/docs/docs/commands.md b/docs/docs/commands.md
@@ -2,7 +2,7 @@
 sidebar_position: 2
 ---
 
-# Commands
+# CLI Reference
 
 PipeCraft provides a focused set of commands designed to get you from zero to a working CI/CD pipeline with minimal friction. Each command serves a specific purpose in your workflow, from initial setup through ongoing maintenance and troubleshooting.
 

diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md