---
name: eck:switch-docs
version: "0.7.4"
description: "Toggle Confluence publishing for the project. Docs always live in docs/ (local-first); this skill enables or disables the Confluence publish channel."
disable-model-invocation: false
---

# Switch Docs

Toggle Confluence publishing for the project. Docs always live in docs/ (local-first); this skill enables or disables the Confluence publish channel.

---

## Visual Framework

Follow the visual framework defined in the `output:visual-framework` primitive.

---

## Task Registration

| Stage | Subject             | Active Form       | Statusline     |
| ----- | ------------------- | ----------------- | -------------- |
| 1     | Stage 1: Pre-Flight | Checking project  | PreFlght (1/5) |
| 2     | Stage 2: Interview  | Gathering config  | Intrvw (2/5)   |
| 3     | Stage 3: Backup     | Backing up files  | Backup (3/5)   |
| 4     | Stage 4: Apply      | Applying changes  | Apply (4/5)    |
| 5     | Stage 5: Finalize   | Updating registry | Finalize (5/5) |

### Statusline Stage Updates

At the **start** of each stage, update the statusline:

```bash
bash $ECK_HOME/update-stage.sh "{Statusline text from table}"
```

At **skill completion** (success or error), reset:

```bash
bash $ECK_HOME/update-stage.sh
```

## Usage

```
/eck:switch-docs
/eck:switch-docs --dry-run
```

| Flag        | Description                                |
| ----------- | ------------------------------------------ |
| `--dry-run` | Show planned changes without applying them |

---

## Stage 1: Pre-Flight

### Inputs

- `.claude/project-constants.md` — current project configuration
- `$ECK_HOME/` — global template source

### Activities

1. Verify this is an ECK-managed project (`.claude/project-constants.md` exists)
   - If missing → STOP: "Not an ECK project. Run `/eck:new-project` first."
2. Read `project-constants.md` and check for `CONFLUENCE_ENABLED`
   - If `DOC_PLATFORM` is found but `CONFLUENCE_ENABLED` is NOT found → STOP with warning:
     "Your project uses the legacy DOC_PLATFORM constant. Run `/eck:update-project` first to migrate to docs-first architecture."
3. Read current `<CONFLUENCE_ENABLED>` value from `project-constants.md`
4. Verify global templates exist at `$ECK_HOME/`
   - If missing → STOP: "ECK global install not found. Run `npx @evolvconsulting/evolv-coder-kit --global`."

### Outputs

- Current `CONFLUENCE_ENABLED` state identified
- Global template source verified

### Exit Criteria

- Project is confirmed ECK-managed and on docs-first architecture
- Current `CONFLUENCE_ENABLED` state is known

---

## Stage 2: Interview

### Inputs

- Current `<CONFLUENCE_ENABLED>` value

### Activities

1. Determine the toggle direction based on current state:
   - If `CONFLUENCE_ENABLED` is currently `true` → ask: "Disable Confluence publishing? Docs remain in docs/."
   - If `CONFLUENCE_ENABLED` is currently `false` → ask: "Enable Confluence publishing?"
2. If enabling Confluence and any of the following constants are not already set in `project-constants.md`, ask for them:
   - `<CONFLUENCE_BASE_URL>` — Confluence base URL
   - `<CONFLUENCE_SPACE_KEY>` — Space key
   - `<CONFLUENCE_SPACE_ID>` — Space ID
   - `<CONFLUENCE_SPACE_NAME>` — Space display name
   - `<CONFLUENCE_HOMEPAGE_ID>` — Homepage page ID (parent for new pages)
3. If disabling Confluence: no additional questions needed
4. If `--dry-run`: display planned changes and exit

### Outputs

- Toggle direction confirmed (enable or disable)
- All required Confluence constants collected (if enabling)

### Exit Criteria

- User has confirmed the toggle action
- All required constants for enabling are provided (if applicable)

---

## Stage 3: Backup

### Inputs

- Toggle direction from Stage 2

### Activities

1. Create backup directory: `.claude-backup-switch-docs-{YYYY-MM-DD}/`
2. Copy the following files to the backup directory:
   - `.claude/project-constants.md`
   - `.claude/project-catalog.yaml`
3. Display backup location

### Outputs

- Backup directory with copies of affected files

### Exit Criteria

- Files are backed up
- Backup directory path is recorded

---

## Stage 4: Apply

### Inputs

- Toggle direction from Stage 2
- Configuration values from Stage 2
- Global templates from `$ECK_HOME/`

### Activities

1. Update `project-constants.md`:
   - Set `CONFLUENCE_ENABLED` to `true` or `false`
   - If enabling: add/update Confluence constants (`CONFLUENCE_BASE_URL`, `CONFLUENCE_SPACE_KEY`, `CONFLUENCE_SPACE_ID`, `CONFLUENCE_SPACE_NAME`, `CONFLUENCE_HOMEPAGE_ID`)
2. If enabling Confluence:
   - Deploy `confluence-official/` primitives from `$ECK_HOME/.claude/primitives/`
   - Deploy `confluence/SKILL.md` skill
3. If disabling Confluence:
   - Remove `confluence-official/` primitives
   - Remove `confluence/SKILL.md` if present
4. `local-docs/` primitives are ALWAYS deployed and MUST NOT be removed regardless of toggle direction
5. If enabling Confluence: run `core/ops:mcp-preflight` inline as a warning-only check (non-blocking):
   - If available: `[x] Confluence MCP: connected`
   - If unavailable: `[!] Confluence MCP: not responding — documentation features will be blocked until configured.`
6. **MUST** run `/eck:update-permissions --auto-apply` to regenerate permissions. Do NOT skip this step.

### Outputs

- `project-constants.md` updated with new `CONFLUENCE_ENABLED` value
- Confluence primitives and skill deployed or removed
- MCP connectivity status displayed (if enabling)
- Permissions regenerated

### Exit Criteria

- `project-constants.md` reflects the new `CONFLUENCE_ENABLED` state
- Correct primitives and skills are deployed or removed
- Permissions have been regenerated

---

## Stage 5: Finalize

### Inputs

- All changes from Stage 4
- `$ECK_HOME/registry.yaml`

### Activities

1. **MUST** update `registry.yaml` for this project. Do NOT skip registry update after a successful switch:
   - Set `doc_platform` to `"local"` (when disabling) or `"local+confluence"` (when enabling)
   - Append to `sync_history`:
     ```yaml
     - date: "<DATE>"
       action: "switch-docs"
       performed_by: "/eck:switch-docs"
       summary: "Confluence publishing {enabled|disabled}"
     ```
   - Atomic write per `ops:registry-update`
2. Display completion summary via the Bash tool:

   ```bash
   source $ECK_HOME/colors.sh

   echo ""
   printf '%b\n' "${ORANGE}${BOLD}Docs Switched${RESET}"
   echo ""
   printf '%b\n' "${GREEN}[x]${RESET} Confluence publishing: {enabled|disabled}"
   printf '%b\n' "${GREEN}[x]${RESET} {N} files updated"
   printf '%b\n' "${GREEN}[x]${RESET} Backup at: .claude-backup-switch-docs-{date}/"
   echo ""
   printf '%b\n' "${DIM}To rollback: restore files from the backup directory.${RESET}"
   echo ""
   ```

3. Reset statusline

### Outputs

- Registry updated with new `doc_platform` value
- Completion summary displayed

### Exit Criteria

- Registry reflects the new documentation platform state
- Summary displayed with rollback instructions

---

## Error Handling

Follow the error handling protocol defined in the `output:error-handler` primitive.

- **Not an ECK project**: STOP with guidance to run `/eck:new-project`
- **Legacy DOC_PLATFORM detected**: STOP with guidance to run `/eck:update-project` first
- **Already in desired state**: STOP: "Confluence publishing is already {enabled|disabled}. No changes needed."
- **Backup failure**: STOP: "Could not create backup. Resolve permissions and retry."
- **Apply failure mid-way**: Display which changes succeeded, point to backup for rollback
- **On error**: Reset the statusline before exiting.
  ```bash
  bash $ECK_HOME/update-stage.sh
  ```

---

## Related Documents

- [/eck:new-project](../new-project/SKILL.md) — Initial project setup with docs platform selection
- [/eck:switch-tracker](../switch-tracker/SKILL.md) — Switch issue tracker
- [docs:router](../../project/primitives/docs/_router.md) — Docs dispatch
- [core/ops:mcp-preflight](../../project/primitives/core/ops/mcp-preflight.md) — MCP validation
