Migrating from Samuel v2 to v3¶

Samuel v3.0.0 reshapes the CLI for clarity. The hot path is init → run → update. Discovery collapses into one verb. Power-user commands move under admin. The autonomous Ralph Wiggum loop gets a guessable name.

v2 scripts keep working through v3.0.x. Every renamed command stays registered as a hidden alias that prints a one-line redirect on stderr and forwards to the new handler. Set SAMUEL_NO_DEPRECATION=1 (or pass --no-deprecation) to silence the redirect noise in CI logs.

The shim removes in v3.1.0, roughly three months after v3.0.0 ships. Plan to update your scripts before then.

Command map¶

Discovery (collapsed into samuel ls)¶

ls --detail infers the type from the registry. If a name is ambiguous (none today, but possible in the future), pass --type to disambiguate.

Component install (type now optional)¶

Both v2 (add framework react) and v3 (add react framework) argument orders work. Type aliases (lang/l, fw/f, wf/w) are still accepted.

Autonomous loop (renamed auto → run, auto is permanent alias)¶

samuel auto X continues to work for every verb forever. It's not deprecated, just non-canonical.

Bare samuel run (or samuel auto) shows status when a loop is initialized. In an empty directory it prints actionable help and exits non-zero — it never silently starts a loop. v2 behavior was the same; v3 just makes the contract explicit.

Power-user commands (config, sync, diff moved under admin)¶

doctor and skill stay top-level — they're trust-building and contributor commands, not admin.

JSON output schema bump¶

The --json envelope now carries "schemaVersion": 3 and the command field reflects the invoked path:

{
  "schemaVersion": 3,
  "command": "ls",
  "success": true,
  "data": { ... }
}

Legacy command paths preserve their v2 command strings:

• samuel list --json → "command": "list"
• samuel auto task complete X --json → "command": "auto task complete"

Pin your consumers to schemaVersion rather than command-name strings if you want forward stability.

CI script migration¶

If your CI invokes Samuel:

1. Quick fix (no script changes): set SAMUEL_NO_DEPRECATION=1 in your CI environment. Legacy commands keep working through v3.0.x with no log noise.
2. Proper fix (script changes): update commands per the tables above. Test locally first; the new forms produce identical output.
3. Long-term: pin to schemaVersion: 3 in JSON consumers if you parse the command field.

Plan to complete step 2 before v3.1.0 ships (~3 months after v3.0.0).

What didn't change¶

• samuel init — same flags, same behavior
• samuel update — same flags except --diff is now Hidden (use --preview)
• samuel doctor — top-level, unchanged
• samuel skill <verb> — top-level, unchanged
• samuel version — unchanged
• AGENTS.md / CLAUDE.md template content — same surface area
• Registry of installable components — same languages, frameworks, workflows, skills

Getting help¶

• samuel <command> --help shows the v3 form for every command
• samuel --help shows the new top-level surface (8 visible commands)
• samuel --help-all (Cobra built-in via aliases) shows hidden legacy commands too
• File issues at https://github.com/ar4mirez/samuel/issues

Why v3 broke the surface¶

The maintainer personally used 3 of 14 commands in daily flow. New users hit a wall of verbs, several of which overlapped (list, search, info all answer "what's there?"). The auto command name told nothing about the autonomous loop being the differentiator.

v3.0.0 trades a one-time migration for a help screen that fits on one terminal page and a verb (run) that says what it does. Hidden+Deprecated aliases mean v2 scripts keep running while you adapt. The migration window is intentionally generous; the verb names are designed to last.