@agentworkforce/cli 0.5.4 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-05-06
+
+### Added
+
+- **Support installable persona sources**
+
+### Fixed
+
+- Isolate cwd personas under personas dir
+- Honor source config with legacy persona dir
+
+### Dependencies
+
+- Inline command name in help
+- Use fixed command name in help
+- Publish only agentworkforce bin
+
 ## [0.5.4] - 2026-05-01
 
 ### Added

package/README.md

@@ -1,59 +1,54 @@
-# agent-workforce CLI
+# agentworkforce CLI
 
 A thin command-line front end for the workload-router. Spawns the harness CLI
 (`claude`, `codex`, `opencode`) configured by a selected **persona** — either a
-built-in one from `/personas/`, or a user-local one that extends a built-in.
+built-in one from `/personas/`, or an installed/local one that extends a lower
+source.
 
 ```
-agent-workforce agent <persona>[@<tier>]
-agent-workforce list [flags]
-agent-workforce harness check
+agentworkforce agent <persona>[@<tier>]
+agentworkforce list [flags]
+agentworkforce show <persona>[@<tier>]
+agentworkforce sources <list|add|remove>
+agentworkforce harness check
 ```
 
 - `agent` — drops you into an interactive session with the harness.
 - `list` — print the persona catalog as a table (or JSON). See
   [`## List`](#list) below for every flag.
+- `show` — print the resolved spec for one persona.
+- `sources` — list, add, or remove persona source directories.
 - `harness check` — probe which harnesses (`claude`, `codex`, `opencode`)
   are installed. See [`## Harness check`](#harness-check) below.
 
 ## Install
 
-The CLI ships under two npm names that point at the same code:
-
-- **`@agentworkforce/cli`** — the scoped package; installs the
-  `agent-workforce` bin.
-- **`agentworkforce`** — a thin top-level wrapper; installs the
-  `agentworkforce` bin so the global install command and command name match
-  (`npm i -g agentworkforce`).
-
-Both depend on `@agentworkforce/workload-router` and `@agentworkforce/harness-kit`
-via the pnpm workspace. The CLI derives its help-text bin name from
-`process.argv[1]`, so `--help` shows whichever name you invoked.
+Install the top-level `agentworkforce` package. It provides the
+`agentworkforce` bin and depends on this internal CLI package.
 
 From npm:
 
 ```sh
-npm i -g agentworkforce      # provides `agentworkforce`
-# or
-npm i -g @agentworkforce/cli # provides `agent-workforce`
+npm i -g agentworkforce
 ```
 
 From the repo checkout:
 
 ```sh
 corepack pnpm -r build
-corepack pnpm --filter @agentworkforce/cli link --global
+corepack pnpm --filter agentworkforce link --global
 ```
 
 ## Selectors
 
 ```
-agent-workforce agent <persona>[@<tier>]
+agentworkforce agent <persona>[@<tier>]
 ```
 
 - `<persona>` — matches, in order:
-  1. A **pwd-local** id (files in `<cwd>/.agent-workforce/*.json`)
-  2. A **home-local** id (files in `~/.agent-workforce/*.json`)
+  1. A **cwd-local** id (files in `<cwd>/.agentworkforce/workforce/personas/*.json`)
+  2. A configured persona source dir, in order. The default is
+     `~/.agentworkforce/workforce/personas/*.json`.
   3. A **library** persona — by intent first (e.g. `review`), then by id
      (e.g. `code-reviewer`)
 - `<tier>` — `best` | `best-value` | `minimum`. Defaults to `best-value`.
@@ -64,23 +59,24 @@ Unknown persona prints the full catalog with each entry's origin.
 
 ```sh
 # Interactive code reviewer
-agent-workforce agent review@best-value
+agentworkforce agent review@best-value
 
 # Interactive PostHog session (library persona, needs POSTHOG_API_KEY)
-agent-workforce agent posthog@best
+agentworkforce agent posthog@best
 
 # Interactive against a local override
-agent-workforce agent my-posthog@best
+agentworkforce agent my-posthog@best
 ```
 
 ## List
 
 ```
-agent-workforce list [flags]
+agentworkforce list [flags]
 ```
 
 Prints the merged persona catalog — everything the `agent` subcommand would
-accept as a selector — including cascade source (`library`, `home`, `pwd`),
+accept as a selector — including cascade source (`library`, `user`, `cwd`,
+or `dir:<n>`),
 harness, model, description, and tier ("rating"). One row per persona-tier
 combination; by default only the **recommended tier per intent** is shown
 (as declared in
@@ -105,28 +101,66 @@ the allowed values.
 
 ```sh
 # Default: one row per persona, recommended tier only
-agent-workforce list
+agentworkforce list
 
 # See every tier
-agent-workforce list --all
+agentworkforce list --all
 
 # Only the top tier across the catalog — independent of recommendations
-agent-workforce list --filter-rating best
+agentworkforce list --filter-rating best
 
 # All claude-harness personas (any tier)
-agent-workforce list --all --filter-harness claude
+agentworkforce list --all --filter-harness claude
 
 # Compact table for a narrow terminal
-agent-workforce list --no-display-description
+agentworkforce list --no-display-description
 
 # Machine-readable
-agent-workforce list --json --filter-harness claude
+agentworkforce list --json --filter-harness claude
+```
+
+## Sources
+
+```
+agentworkforce sources list [--json]
+agentworkforce sources add <dir> [--position <n>]
+agentworkforce sources remove <dir|config-position>
+```
+
+The fixed project source is always first:
+`<cwd>/.agentworkforce/workforce/personas/*.json`.
+
+After that, the CLI reads an ordered list of configurable persona directories
+from `~/.agentworkforce/workforce/config.json`. If no config exists, the list
+defaults to `~/.agentworkforce/workforce/personas`. This makes installed
+personas work as plain JSON files in the default user location, or from any
+checked-out repo you add as a source directory.
+
+`sources add` appends by default. `--position <n>` inserts at the 1-based
+position among configurable directories, so `--position 1` gives that directory
+the highest priority after the fixed cwd source. `sources remove` accepts either
+that configurable position or an exact path.
+
+Examples:
+
+```sh
+# Show the full source cascade, including fixed cwd and library entries
+agentworkforce sources list
+
+# Install personas from another checkout, below the default user persona dir
+agentworkforce sources add ~/src/company-personas/personas
+
+# Give a checked-out persona repo priority over the default user dir
+agentworkforce sources add ~/src/company-personas/personas --position 1
+
+# Remove the first configurable persona source
+agentworkforce sources remove 1
 ```
 
 ## Harness check
 
 ```
-agent-workforce harness check
+agentworkforce harness check
 ```
 
 Probes your PATH for each supported harness binary (`claude`, `codex`,
@@ -169,17 +203,21 @@ See `/personas/*.json` for all built-ins.
 Local persona files layer on top of the library. Resolution precedence (highest
 wins):
 
-1. `<cwd>/.agent-workforce/*.json` — **pwd**
-2. `~/.agent-workforce/*.json` — **home** (override path via
-   `AGENT_WORKFORCE_CONFIG_DIR`)
+1. `<cwd>/.agentworkforce/workforce/personas/*.json` — **cwd**
+2. Configurable persona source dirs, in order. Default:
+   `~/.agentworkforce/workforce/personas/*.json` — **user**
 3. Built-in personas in `/personas/` — **library**
 
 Local files are **partial overlays**: only the fields you set replace the
 inherited value. Everything else cascades through from below.
 
+Set `AGENT_WORKFORCE_HOME` to move the `~/.agentworkforce/workforce` config
+root. The legacy `AGENT_WORKFORCE_CONFIG_DIR` env var is still honored as a
+direct override for the default user persona directory.
+
 ### Minimal override: add your API key
 
-`~/.agent-workforce/my-posthog.json`:
+`~/.agentworkforce/workforce/personas/my-posthog.json`:
 
 ```json
 {
@@ -190,7 +228,7 @@ inherited value. Everything else cascades through from below.
 ```
 
 That inherits every field from the library `posthog` persona, then layers your
-`env` on top. `agent-workforce agent my-posthog@best` now works as long as
+`env` on top. `agentworkforce agent my-posthog@best` now works as long as
 `POSTHOG_API_KEY` is exported in your shell.
 
 ### Same-id override (implicit extends)
@@ -198,7 +236,7 @@ That inherits every field from the library `posthog` persona, then layers your
 If your file's `id` matches a persona in a lower layer and you omit `extends`,
 the loader implicitly inherits from that same-id base:
 
-`<cwd>/.agent-workforce/posthog.json`:
+`<cwd>/.agentworkforce/workforce/personas/posthog.json`:
 
 ```json
 {
@@ -207,29 +245,30 @@ the loader implicitly inherits from that same-id base:
 }
 ```
 
-Resolving `posthog` now hits this pwd override first; it inherits the rest
+Resolving `posthog` now hits this cwd override first; it inherits the rest
 (MCP, tiers, description, etc.) from the library `posthog`.
 
 ### Cascade chain
 
-A pwd file can extend a home file, which extends the library:
+A cwd file can extend a user or configured-dir file, which extends the library:
 
 ```
-~/.agent-workforce/ph-base.json:
+~/.agentworkforce/workforce/personas/ph-base.json:
 { "id": "ph-base", "extends": "posthog", "env": { "POSTHOG_ORG": "acme" } }
 
-<cwd>/.agent-workforce/ph-prod.json:
+<cwd>/.agentworkforce/workforce/personas/ph-prod.json:
 { "id": "ph-prod", "extends": "ph-base", "env": { "POSTHOG_API_KEY": "$PROD_KEY" } }
 ```
 
 Resolving `ph-prod`:
 
 - Start with library `posthog` (MCP, tiers, prompt, …)
-- Layer home `ph-base` on top (adds `POSTHOG_ORG=acme`)
-- Layer pwd `ph-prod` on top (adds `POSTHOG_API_KEY`)
+- Layer user `ph-base` on top (adds `POSTHOG_ORG=acme`)
+- Layer cwd `ph-prod` on top (adds `POSTHOG_API_KEY`)
 
-`extends` is resolved **strictly against lower layers** — pwd extends home or
-library, home extends library, library has no `extends`.
+`extends` is resolved **strictly against lower layers** — cwd extends configured
+dirs or library, configured dirs extend lower configured dirs or library, and
+library has no `extends`.
 
 ### Override shape (all fields except `id` optional)
 
@@ -320,9 +359,9 @@ eyeball.
   warning and fall back to their defaults when `permissions` is set.
 - **Cascade merge:** `allow` and `deny` are unions across layers (deduped on
   merge); `mode` is replaced by the topmost layer that sets it. So the
-  library can declare the minimum-viable allow list, home can layer on
-  project-wide denies, and pwd can add per-project patterns — they all
-  compose.
+  library can declare the minimum-viable allow list, a user or configured
+  persona source can layer shared denies, and cwd can add per-project patterns
+  — they all compose.
 
 ### Example: PostHog with auto-approve
 
@@ -392,7 +431,7 @@ persona session, add it to the persona's `mcpServers` block.
 ## Interactive
 
 ```sh
-agent-workforce agent [--install-in-repo] <persona>[@<tier>]
+agentworkforce agent [--install-in-repo] <persona>[@<tier>]
 ```
 
 By default, claude and opencode sessions run inside a sandbox mount — see
@@ -467,7 +506,7 @@ Pass `--install-in-repo` to fall back to the legacy behavior (skills land in
 the repo's `.claude/skills/` directory, cleaned on exit):
 
 ```sh
-agent-workforce agent --install-in-repo code-reviewer@best
+agentworkforce agent --install-in-repo code-reviewer@best
 ```
 
 Useful when you want to inspect the installed skills on disk, or when the
@@ -555,7 +594,7 @@ is generated once and both paths are derived from it:
 
 `@relayfile/local-mount` handles mount creation, process spawn,
 SIGINT/SIGTERM forwarding, write syncback, and cleanup on exit. The
-agent-workforce CLI just wires the paths and passes the persona's argv.
+agentworkforce CLI just wires the paths and passes the persona's argv.
 
 ### Example
 
@@ -564,7 +603,7 @@ agent-workforce CLI just wires the paths and passes the persona's argv.
 # .mcp.json hidden — session sees the persona's staged skills plus your
 # user-level ~/.claude/CLAUDE.md, nothing else from this repo.
 export POSTHOG_API_KEY=phx_…
-agent-workforce agent posthog@best
+agentworkforce agent posthog@best
 ```
 
 On exit: mount is synced back to the real repo, then torn down; skill

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAQA,OAAO,EAOL,KAAK,OAAO,EAMb,MAAM,iCAAiC,CAAC;AA6IzC;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAExF;AA4ID;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAe5D;AAED;;;kDAGkD;AAClD,eAAO,MAAM,sBAAsB,mEAKzB,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B,8IAajC,CAAC;AAEX;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAU7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAuCxF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,aAAa,UAAQ,GACpB;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAKvB;AAwxBD,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAiD1C;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACvD,KAAK,EAAE,UAAU,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAwBA"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAQA,OAAO,EAOL,KAAK,OAAO,EAMb,MAAM,iCAAiC,CAAC;AA+IzC;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAExF;AA4ID;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAe5D;AAED;;;kDAGkD;AAClD,eAAO,MAAM,sBAAsB,mEAKzB,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B,8IAajC,CAAC;AAEX;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAU7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAuCxF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,aAAa,UAAQ,GACpB;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAKvB;AAu+BD,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAqD1C;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACvD,KAAK,EAAE,UAAU,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAwBA"}

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { appendFileSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { constants, homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve as resolvePath } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -9,24 +9,8 @@ import { HARNESS_VALUES, PERSONA_TAGS, PERSONA_TIERS, personaCatalog, routingPro
 import { buildInteractiveSpec, detectHarnesses, formatDropWarnings, resolveMcpServersLenient, resolveStringMapLenient } from '@agentworkforce/harness-kit';
 import { launchOnMount } from '@relayfile/local-mount';
 import ora from 'ora';
-import { loadLocalPersonas } from './local-personas.js';
-// Derived from the binary the user actually invoked. Lets the same dist file
-// drive multiple npm bins (`agent-workforce` from @agentworkforce/cli,
-// `agentworkforce` from the top-level wrapper package) without baking either
-// name into the help text. Falls back to `agent-workforce` for the bare
-// `node dist/cli.js` case so the test suite, which spawns cli.js directly,
-// still sees the historical name.
-const BIN_NAME = (() => {
-    const arg1 = process.argv[1];
-    if (!arg1)
-        return 'agent-workforce';
-    const base = arg1.split(/[/\\]/).pop() ?? '';
-    const stripped = base.replace(/\.(m?js|cjs)$/, '');
-    if (!stripped || stripped === 'cli')
-        return 'agent-workforce';
-    return stripped;
-})();
-const USAGE = `Usage: ${BIN_NAME} <command> [args...]
+import { buildPersonaSourceDirectories, loadLocalPersonas, loadPersonaSourceConfig, normalizePersonaDir, savePersonaSourceConfig } from './local-personas.js';
+const USAGE = `Usage: agentworkforce <command> [args...]
 
 Commands:
   agent [flags] <persona>[@<tier>]
@@ -49,10 +33,10 @@ Commands:
                                             are hidden from the session. Codex
                                             sessions never mount and ignore
                                             this flag.
-  list [flags]        List available personas from the cascade (pwd → home →
-                      library). By default shows one row per persona at the
-                      recommended tier for its intent; pass --all to see every
-                      tier. Flags:
+  list [flags]        List available personas from the cascade (cwd →
+                      configured persona dirs → library). By default shows
+                      one row per persona at the recommended tier for its
+                      intent; pass --all to see every tier. Flags:
                         --all                         show every tier (overrides default)
                         --json                        emit JSON instead of a table
                         --filter-rating <tier>        only show this tier; disables
@@ -65,28 +49,38 @@ Commands:
                         --no-display-description      hide the DESCRIPTION column
   show <persona>[@<tier>]
                       Print the fully-resolved spec for a single persona,
-                      including which cascade layer defined it (pwd, home,
-                      library). By default shows only the recommended tier for
-                      the persona's intent; pass @<tier> to pick one, or --all
-                      to see every tier. Flags:
+                      including which cascade layer defined it (cwd, user,
+                      dir:<n>, library). By default shows only the recommended
+                      tier for the persona's intent; pass @<tier> to pick one,
+                      or --all to see every tier. Flags:
                         --all         include every tier (overrides default)
                         --json        emit the resolved PersonaSpec as JSON
+  sources list [--json]
+                      List persona source directories in cascade order.
+  sources add <dir> [--position <n>]
+                      Add a configurable persona source directory. Position is
+                      1-based among configurable dirs after the fixed cwd dir.
+  sources remove <dir|n>
+                      Remove a configurable persona source directory by path or
+                      1-based configurable position.
   harness check       Probe which harnesses (claude, codex, opencode) are
                       installed and runnable on this machine.
 
-Local personas cascade: <cwd>/.agent-workforce/*.json → ~/.agent-workforce/*.json → repo library.
+Local personas cascade: <cwd>/.agentworkforce/workforce/personas/*.json → configured persona dirs → repo library.
 Each layer only needs to specify fields it overrides; everything else inherits
 from the next lower layer. "extends" explicitly names a base; omit it and the
-loader implicitly inherits from the same-id persona below. (Override the home
-layer path via AGENT_WORKFORCE_CONFIG_DIR.)
+loader implicitly inherits from the same-id persona below. By default the only
+configured persona dir is ~/.agentworkforce/workforce/personas.
 
 Examples:
-  ${BIN_NAME} agent npm-provenance-publisher@best
-  ${BIN_NAME} agent my-posthog@best
-  ${BIN_NAME} agent review@best-value
-  ${BIN_NAME} list
-  ${BIN_NAME} show posthog
-  ${BIN_NAME} harness check
+  agentworkforce agent npm-provenance-publisher@best
+  agentworkforce agent my-posthog@best
+  agentworkforce agent review@best-value
+  agentworkforce list
+  agentworkforce show posthog
+  agentworkforce sources list
+  agentworkforce sources add ../my-personas --position 1
+  agentworkforce harness check
 `;
 function die(msg, withUsage = true) {
     process.stderr.write(`${msg}\n`);
@@ -792,6 +786,197 @@ function formatAvailabilityTable(results) {
     const line = (row) => cols.map((c) => row[c].padEnd(widths[c])).join('  ').trimEnd();
     return [line(headers), ...rows.map(line)].join('\n') + '\n';
 }
+function collectSourceDirRows() {
+    const { directories, config } = buildPersonaSourceDirectories();
+    const rows = directories.map((sourceDir, idx) => ({
+        cascade: String(idx + 1),
+        config: sourceDir.configurable ? String(config.personaDirs.indexOf(sourceDir.dir) + 1) : '-',
+        source: sourceDir.source,
+        exists: existsSync(sourceDir.dir) ? 'yes' : 'no',
+        dir: sourceDir.dir
+    }));
+    rows.push({
+        cascade: String(rows.length + 1),
+        config: '-',
+        source: 'library',
+        exists: 'yes',
+        dir: '(built-in)'
+    });
+    return { configPath: config.configPath, personaDirs: config.personaDirs, rows };
+}
+function formatSourcesTable(rows, configPath) {
+    const headers = {
+        cascade: 'CASCADE',
+        config: 'CONFIG',
+        source: 'SOURCE',
+        exists: 'EXISTS',
+        dir: 'DIR'
+    };
+    const cols = ['cascade', 'config', 'source', 'exists', 'dir'];
+    const widths = Object.fromEntries(cols.map((c) => [c, Math.max(headers[c].length, ...rows.map((r) => r[c].length))]));
+    const line = (row) => cols.map((c) => row[c].padEnd(widths[c])).join('  ').trimEnd();
+    return [
+        `Config: ${configPath}`,
+        [line(headers), ...rows.map(line)].join('\n'),
+        ''
+    ].join('\n');
+}
+function parseSourcesListArgs(args) {
+    let json = false;
+    for (const arg of args) {
+        if (arg === '--json') {
+            json = true;
+        }
+        else if (arg === '-h' || arg === '--help') {
+            process.stdout.write('Usage: agentworkforce sources list [--json]\n');
+            process.exit(0);
+        }
+        else {
+            die(`sources list: unexpected argument "${arg}".`);
+        }
+    }
+    return { json };
+}
+function runSourcesList(args) {
+    const { json } = parseSourcesListArgs(args);
+    const { configPath, personaDirs, rows } = collectSourceDirRows();
+    if (json) {
+        process.stdout.write(JSON.stringify({ configPath, personaDirs, sources: rows }, null, 2) + '\n');
+    }
+    else {
+        process.stdout.write(formatSourcesTable(rows, configPath));
+    }
+    process.exit(0);
+}
+function assertDirectoryForAdd(dir) {
+    try {
+        if (!existsSync(dir)) {
+            die(`sources add: directory does not exist: ${dir}`);
+        }
+        if (!statSync(dir).isDirectory()) {
+            die(`sources add: path is not a directory: ${dir}`);
+        }
+    }
+    catch (err) {
+        if (err.message.startsWith('sources add:'))
+            throw err;
+        die(`sources add: could not inspect ${dir}: ${err.message}`);
+    }
+}
+function parseSourcesAddArgs(args) {
+    let dir;
+    let position;
+    const valueOf = (i, flag) => {
+        const v = args[i + 1];
+        if (v === undefined || v.startsWith('--')) {
+            die(`sources add: ${flag} requires a value.`);
+        }
+        return v;
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '-h' || arg === '--help') {
+            process.stdout.write('Usage: agentworkforce sources add <dir> [--position <n>]\n');
+            process.exit(0);
+        }
+        else if (arg === '--position') {
+            const raw = valueOf(i++, arg);
+            const parsed = Number(raw);
+            if (!Number.isInteger(parsed) || parsed < 1) {
+                die(`sources add: --position must be a positive integer.`);
+            }
+            position = parsed;
+        }
+        else if (arg.startsWith('--')) {
+            die(`sources add: unexpected flag "${arg}".`);
+        }
+        else if (dir === undefined) {
+            dir = arg;
+        }
+        else {
+            die(`sources add: unexpected argument "${arg}".`);
+        }
+    }
+    if (!dir)
+        die('sources add: missing directory.');
+    return { dir, position };
+}
+function runSourcesAdd(args) {
+    const { dir: rawDir, position } = parseSourcesAddArgs(args);
+    const dir = normalizePersonaDir(rawDir);
+    assertDirectoryForAdd(dir);
+    const config = loadPersonaSourceConfig();
+    if (config.personaDirs.includes(dir)) {
+        die(`sources add: directory is already configured: ${dir}`);
+    }
+    const insertAt = position === undefined ? config.personaDirs.length : position - 1;
+    if (insertAt < 0 || insertAt > config.personaDirs.length) {
+        die(`sources add: --position must be between 1 and ${config.personaDirs.length + 1}.`);
+    }
+    const nextDirs = [...config.personaDirs];
+    nextDirs.splice(insertAt, 0, dir);
+    const saved = savePersonaSourceConfig(nextDirs);
+    process.stdout.write(`Added persona source directory at configurable position ${insertAt + 1}: ${dir}\nConfig: ${saved.configPath}\n`);
+    process.exit(0);
+}
+function parseSourcesRemoveArgs(args) {
+    let target;
+    for (const arg of args) {
+        if (arg === '-h' || arg === '--help') {
+            process.stdout.write('Usage: agentworkforce sources remove <dir|config-position>\n');
+            process.exit(0);
+        }
+        else if (arg.startsWith('--')) {
+            die(`sources remove: unexpected flag "${arg}".`);
+        }
+        else if (target === undefined) {
+            target = arg;
+        }
+        else {
+            die(`sources remove: unexpected argument "${arg}".`);
+        }
+    }
+    if (!target)
+        die('sources remove: missing directory or config-position.');
+    return { target };
+}
+function runSourcesRemove(args) {
+    const { target } = parseSourcesRemoveArgs(args);
+    const config = loadPersonaSourceConfig();
+    let idx;
+    if (/^[1-9]\d*$/.test(target)) {
+        idx = Number(target) - 1;
+    }
+    else {
+        const dir = normalizePersonaDir(target);
+        idx = config.personaDirs.indexOf(dir);
+    }
+    if (idx < 0 || idx >= config.personaDirs.length) {
+        die(`sources remove: no configurable persona source matched "${target}".`);
+    }
+    const nextDirs = [...config.personaDirs];
+    const [removed] = nextDirs.splice(idx, 1);
+    const saved = savePersonaSourceConfig(nextDirs);
+    process.stdout.write(`Removed persona source directory from configurable position ${idx + 1}: ${removed}\nConfig: ${saved.configPath}\n`);
+    process.exit(0);
+}
+function runSources(args) {
+    const [action, ...rest] = args;
+    if (!action || action === '-h' || action === '--help') {
+        process.stdout.write('Usage: agentworkforce sources <list|add|remove> [args...]\n' +
+            '  agentworkforce sources list [--json]\n' +
+            '  agentworkforce sources add <dir> [--position <n>]\n' +
+            '  agentworkforce sources remove <dir|config-position>\n');
+        process.exit(action ? 0 : 1);
+    }
+    if (action === 'list')
+        runSourcesList(rest);
+    if (action === 'add')
+        runSourcesAdd(rest);
+    if (action === 'remove')
+        runSourcesRemove(rest);
+    die(`sources: unknown action "${action}". Expected: list, add, remove.`);
+}
 function collectPersonaRows() {
     const rows = [];
     const pushSpec = (spec, source) => {
@@ -897,7 +1082,7 @@ function parseListArgs(args) {
             json = true;
         }
         else if (arg === '-h' || arg === '--help') {
-            process.stdout.write(`Usage: ${BIN_NAME} list [--all] [--json] [--filter-rating <tier>] [--filter-harness <harness>] [--filter-tag <tag>] [--no-display-description]\n`);
+            process.stdout.write('Usage: agentworkforce list [--all] [--json] [--filter-rating <tier>] [--filter-harness <harness>] [--filter-tag <tag>] [--no-display-description]\n');
             process.exit(0);
         }
         else if (arg === '--all' || arg === '--no-recommended') {
@@ -981,7 +1166,7 @@ function parseShowArgs(args) {
             all = true;
         }
         else if (arg === '-h' || arg === '--help') {
-            process.stdout.write(`Usage: ${BIN_NAME} show <persona>[@<tier>] [--all] [--json]\n`);
+            process.stdout.write('Usage: agentworkforce show <persona>[@<tier>] [--all] [--json]\n');
             process.exit(0);
         }
         else if (arg.startsWith('--')) {
@@ -1019,7 +1204,7 @@ function resolveShowTarget(selector, all) {
     let source = 'library';
     if (localSpec) {
         spec = localSpec;
-        source = local.sources.get(key) ?? 'pwd';
+        source = local.sources.get(key) ?? 'cwd';
     }
     else {
         const byIntent = personaCatalog[key];
@@ -1175,6 +1360,9 @@ export async function main() {
     if (subcommand === 'show') {
         runShow(rest);
     }
+    if (subcommand === 'sources') {
+        runSources(rest);
+    }
     if (subcommand === 'harness') {
         const [action, ...extra] = rest;
         if (!action || action === '-h' || action === '--help') {