v3.6.28

> Closes 3 of 5 papercuts in #1744 (the methodical install study) plus 3 runtime-honesty fixes. Already on npm; tags `latest`, `alpha`, `v3alpha` consistent across all 3 packages.

```bash
npx @claude-flow/cli@3.6.28
npx claude-flow@3.6.28
npx ruflo@3.6.28
```

## What's new

### `--no-global` flag (#1744 #2)

Opt out of the user-global `~/.claude/CLAUDE.md` "Ruflo Integration" pointer block. Default behavior unchanged (idempotent append), but users who want to keep the global rules file pristine can now run:

```bash
npx ruflo@latest init --no-global
```

The skipped file is reported in the install summary so it's no longer invisible.

### `--minimal` no longer ships orphan hooks (#1744 #3)

Before: `--minimal` wrote `.claude/settings.json` with hook decls pointing at `.claude/helpers/hook-handler.cjs` but didn't install the helpers — every hook fired and silently failed.

After: settings.json hook block is gated on `components.helpers`. `--minimal` produces a hook-free settings.json. Minimal stays minimal AND functional.

### README install paths labeled (#1744 #1)

Replaced the single "Recommended" Quick Start with a head-to-head table:

| | Claude Code Plugin | CLI install (`npx ruflo init`) |
|---|---|---|
| Files in workspace | Zero | `.claude/`, `.claude-flow/`, helpers, settings |
| MCP server registered | No | Yes |
| Hooks installed | No | Yes |
| Best for | Try a single plugin's commands | Production use |

### Runtime honesty fixes (bundled)

- **`commands/performance.ts`** — drop unverified "Flash Attention 2.49× speedup" recommendation; re-tag as "in progress, JS reference impl"
- **`mcp-tools/neural-tools.ts`** — drop silent Tier-4 mock-embedding fallback; let downstream see a clear `_embeddingNote` instead of pretending mock embeddings are real
- **`embeddings/embedding-service.ts`** — throw on unknown provider / no-real-provider-available paths instead of silently substituting `MockEmbeddingService`

### Doc cleanup (PR #1751, also in this release)

- 5 occurrences of `init --wizard` → `init wizard` across README + USERGUIDE (per `init.ts:445-447` `wizardCommand` is a registered subcommand, not a flag)
- README MCP add command: `npx -y @claude-flow/cli@latest` → `npx ruflo@latest mcp start` (matches USERGUIDE)

### Coder agents now read ADRs (PR #1752, fixes #1749)

Three coder agent definitions updated to declare `docs/adr/*.md` as authoritative inputs alongside `docs/SPEC.md`:
- `.claude/agents/core/coder.md`
- `.claude/agents/templates/implementer-sparc-coder.md`
- `plugins/ruflo-core/agents/coder.md`

Each now mandates reading both documents before architecture/scope-affecting work, with explicit "ADRs are binding unless superseded" + "in multi-agent parallel implementation, ADRs are the cross-agent contract" framing.

### Cost-tracker consistency audit (PR #1750, v0.16.1)

The cost-tracker plugin's agent file (`cost-analyst.md`) only mentioned 3 of 13 skills (8 capabilities silently invisible to spawned agents); README skills table missing 4 rows. All fixed; new smoke checks (now 48/48) prevent recurrence.

## Verify locally

```bash
# New flag exists
npx @claude-flow/cli@3.6.28 init --help | grep no-global

# Run init without global rules-file append
npx ruflo@3.6.28 init --no-global

# Minimal no longer ships orphan hooks
npx ruflo@3.6.28 init --minimal --force
cat .claude/settings.json   # should NOT have a 'hooks' block
```

## Witness manifest

`verification.md` + `verification.md.json` regenerated for 3.6.28 — **55 verified fixes** (was 27 at 3.6.24). Adds CAP-MCP capability inventory: 300 tools across 28 source files. Manifest hash + Ed25519 signature re-derived from current git commit.

## Closes

- #1744 (install study — papercuts #1, #2, #3, #4, #5)
- #1749 (coder agents ignore ADRs)

## Pull requests merged

- #1750 — cost-tracker v0.16.1 consistency audit
- #1751 — README/USERGUIDE init drift fixes
- #1752 — coder agents read ADRs
- #1753 — #1744 honest defaults + runtime fallbacks (the npm release)

## Thanks

Special thanks to the reporter of #1744 — methodical install studies are the highest-leverage feedback we get. This release closes 3 of the 5 papercuts; the remaining 2 are doc-only and shipped via PR #1751.

🤖 Generated with [RuFlo](https://github.com/ruvnet/ruflo)