@ajaykumarnpm/talea 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to this project are recorded here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the versions follow
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-09-22
+
+### Added
+- run commands from outside a workspace
+
+## [0.4.0] - 2026-09-22
+
+### Added
+- talea skill, and the CLI in the design system's palette
+
+### Fixed
+- **test**: skill.test.js asserted LF against a CRLF checkout
+- **test**: init.test.js depended on the author's own GitHub auth
+- create group folders only when cloning
+
+### Documentation
+- the site and the manual, at talea-run.web.app
+
 ## [0.3.0] - 2026-09-21
 
 ### Added

package/README.md

@@ -2,6 +2,8 @@
 
 **One folder structure for every machine you work on.**
 
+[talea-run.web.app](https://talea-run.web.app) — the site, and [the manual](https://talea-run.web.app/docs/).
+
 You have a laptop, a desktop, and a work machine. On each one, the repo you want
 is either missing or somewhere you have to go and find. `talea` fixes that: one
 catalogue of your GitHub repos, one tree, and a command that makes any machine
@@ -44,6 +46,9 @@ talea manifest push          # publish the catalogue so the next machine can rea
 repos, every org you belong to, and anything shared with you directly. It then
 asks what this machine should keep and fills the tree.
 
+Every command works from anywhere after that. Outside the workspace it uses
+the one `init` made; with more than one on the machine, it asks which.
+
 ## Every machine after that
 
 ```sh
@@ -64,6 +69,21 @@ talea select                 # reopen the checklist and change the whole list
 cd $(talea where eklavya)
 ```
 
+## Let your coding agent do it
+
+```sh
+talea skill install
+```
+
+Installs a skill into Claude Code at **user scope**, so every project you open
+has it. After that `"where is eklavya?"` and `"my repos are scattered, tidy them
+up"` reach the right command — with the guardrails attached: an adopt is always
+shown as a dry run first, `--loose` is never taken on your behalf, and a removal
+is reported as *taken off the list* rather than as a delete.
+
+`talea skill` says whether it is installed, `talea skill uninstall` takes it back
+out, and it refuses to overwrite a skill called `talea` that talea did not write.
+
 ---
 
 ## The repos you already have
@@ -154,6 +174,7 @@ Treat the id like a bookmark you would not paste into a public channel.
 | `talea tree` | the folder tree on disk |
 | `talea exec -- <cmd>` | run one command in every repo |
 | `talea manifest push/pull` | move the catalogue between machines |
+| `talea skill` | install the skill that lets your coding agent drive talea |
 | `talea doctor` | check this machine can do the work |
 | `talea upgrade` | update the CLI itself |
 
@@ -195,6 +216,14 @@ node bin/talea.js --help
 
 Tests run on macOS, Linux and Windows across Node 20, 22 and 24 on every push.
 
+The website lives in `web/` and is its own thing — Astro, deployed to Firebase
+Hosting on a push to `main` that touches it. `web/CLAUDE.md` is how to work on
+it.
+
+```sh
+cd web && npm install && npm run dev
+```
+
 ## Licence
 
 MIT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ajaykumarnpm/talea",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "One folder structure for every machine. Clone, adopt and sync your GitHub repos from a manifest you own.",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "bin",
     "src",
     "manifest",
+    "skills",
     "templates",
     "README.md",
     "CHANGELOG.md"

package/skills/talea/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: talea
+description: "Operate talea, the CLI that gives every machine the same folder structure for its GitHub repos. Use when the user asks where a repo is, to clone or sync or pull their repos, to tidy or reorganise a workspace, to adopt checkouts that are in the wrong place, to change what this machine keeps, or to move their repo catalogue to another machine. Also use before running a command in several repos at once. Do not use for ordinary git work inside one repo that is already checked out."
+---
+
+<!-- talea-skill: installed by `talea skill install`; edits are overwritten -->
+
+# talea
+
+`talea` keeps one folder structure across every machine a developer works on.
+It holds a catalogue of their GitHub repos, moves checkouts they already have
+into place, clones what is missing, and fast-forwards the rest.
+
+Two rules make it safe to hand to an agent: it never pushes, and it never
+deletes. Everything below leans on that.
+
+## Find the binary first
+
+```bash
+command -v talea
+```
+
+That prints the path, or nothing. It is installed with
+`npm install -g @ajaykumarnpm/talea` — the package is scoped, the command is
+not. If it prints nothing, fall back to `npx -y @ajaykumarnpm/talea <command>`,
+which downloads on first use. If that fails too, say talea is not installed and
+give the one install command rather than guessing at a path.
+
+Shell variables do not survive between tool calls, so write the resolved path
+into every later command rather than setting `T=` and hoping.
+
+Everything below writes `talea` for readability. Substitute whatever the line
+above resolved to.
+
+## Where is this repo?
+
+This is the command to reach for most, and the reason the tool exists.
+
+```bash
+talea where eklavya          # the absolute path, one line, nothing else
+cd "$(talea where eklavya)"  # what it is actually for
+talea where                  # the workspace root
+```
+
+It exits **non-zero** on an unknown name and writes every diagnostic to stderr,
+so `cd "$(talea where typo)"` fails instead of landing in the home directory.
+Never `cd` to a path it did not print.
+
+Outside a workspace it falls back to the ones this machine has. With several
+and no terminal — which is how you run it — it lists them and exits non-zero.
+`cd` into the workspace the user means rather than guessing from the list.
+
+Two owners can own a repo of the same name. When that happens it says so and
+exits non-zero — pass `owner/name` rather than picking one.
+
+## Read before you write
+
+None of these change anything on disk. Run one before proposing work.
+
+| Command | Answers |
+|---|---|
+| `talea status` | branch, clean or dirty, ahead or behind, for every repo this machine keeps |
+| `talea list` | the catalogue — every repo, its group, its folder |
+| `talea tree` | the folder tree as it actually is on disk |
+| `talea doctor` | can this machine do the work: git, SSH, GitHub auth, the workspace |
+| `talea adopt` | what a move *would* do. It changes nothing without `--apply` |
+
+`talea status` is the one to run before suggesting a sync — a dirty repo is
+skipped, and saying so up front is better than reporting it afterwards.
+
+## Bringing a machine into line
+
+```bash
+talea sync                   # clone what is missing, fast-forward what is there
+talea clone                  # clone only — never fetches or merges
+talea sync -g NonStop        # one group
+talea sync -r eklavya        # one repo
+```
+
+`sync` is safe to run unattended. It fast-forwards **the branch you are on** and
+leaves anything else alone with a line saying why. It never switches branches,
+never merges a divergence and never pushes.
+
+Every bulk command exits non-zero if **any** repo failed, so check the exit
+code — the per-repo errors are printed but the run keeps going.
+
+## Adoption: the one that moves things
+
+A repo the developer already has, in the wrong folder, is **moved** into place
+rather than re-cloned. A move keeps branches, stashes, the reflog and
+uncommitted work; a re-clone throws all of it away.
+
+```bash
+talea adopt                    # show what would move, change nothing
+talea adopt --from ~/Desktop   # look there too; the folder is remembered
+talea adopt --apply            # do it
+```
+
+**Always run it without `--apply` first and show the developer the plan.** A
+move relocates directories they may have open in an editor, a terminal or a
+long-running process.
+
+Matching is on the **git remote URL**, not the folder name. When only the name
+matches — a fork, a mirror, an SDK cache — it is listed and left alone. `--loose`
+or `-r <repo>` includes it. Do not reach for `--loose` on the developer's behalf:
+the guard exists because an FVM Flutter SDK cache reports `origin` as
+`flutter/flutter` and name-matches a personal fork, and adopting it breaks every
+Flutter project on the machine.
+
+A second copy of the same repo is **parked** in `.talea-duplicates/`, not
+deleted. Say so when it happens — clearing that folder is the developer's call,
+and nothing in talea will do it for them.
+
+## What this machine keeps
+
+```bash
+talea add some-repo     # keep one more here, and clone it now
+talea rm some-repo      # stop keeping it — the checkout stays exactly where it is
+talea select            # reopen the whole checklist, interactively
+```
+
+`talea select` needs a terminal. In a non-interactive session it prints a
+summary instead of hanging, so prefer `add` and `rm` when acting on the
+developer's behalf and leave `select` as something to suggest they run.
+
+`rm` does **not** delete the checkout. Say that plainly when you run it, or it
+reads like data loss.
+
+## Running one command everywhere
+
+```bash
+talea exec -- git status --short
+talea exec -g NonStop -- npm test
+```
+
+Everything after `--` runs in each repo. Treat it as you would any command run
+in N repositories at once: read-only commands freely, anything that writes only
+when the developer asked for it by name.
+
+## Moving the catalogue between machines
+
+```bash
+talea manifest push            # publish it; prints a gist id
+talea manifest pull <gist-id>  # on the next machine
+```
+
+The gist is **private**, but it still carries the names of private
+repositories. Treat the id as something not to paste into a public channel, and
+do not print it into a message that is going somewhere shared.
+
+The split that matters: the **catalogue** travels, the **selection** does not.
+Pulling it onto a new laptop hands over the full list to choose from, never the
+last machine's choices. So `manifest pull` alone changes nothing about what is
+cloned — `talea init` or `talea select` after it is what fills the tree.
+
+## Narrowing any run
+
+Every command takes `-g <group>` and `-r <repo>`, both repeatable, and `--help`
+for its own examples. An unknown group or repo name **exits non-zero** rather
+than quietly doing nothing, so a typo is loud.
+
+## Rules
+
+- **Never `--apply` an adopt the developer has not seen the dry run of.**
+- **Never `--loose`** unless they have looked at the name-only matches and said
+  which one they want.
+- Report a move as *moved*, a removal as *taken off the list*, and a duplicate
+  as *parked*. Those are three different things and the words are the whole
+  safety story.
+- Do not add `ignore: true` to a catalogue entry to work around a conflict
+  without saying so — it means another tool owns that checkout, and every talea
+  command will skip it from then on.
+- talea never pushes. If a repo is ahead of its remote, report it and stop;
+  pushing is the developer's call and not talea's job.
+- A bulk command that exits non-zero has a failed repo in it. Read the output
+  for the failures rather than reporting the run as done.

package/src/cli.js

@@ -20,6 +20,7 @@ import * as manifest from './commands/manifest.js';
 import * as doctor from './commands/doctor.js';
 import * as exec from './commands/exec.js';
 import * as upgrade from './commands/upgrade.js';
+import * as skill from './commands/skill.js';
 import { notifyIfOutdatedAsync } from './update.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
@@ -41,6 +42,7 @@ const COMMANDS = {
   manifest,
   doctor,
   exec,
+  skill,
   upgrade,
 };
 
@@ -59,6 +61,7 @@ const ALIASES = {
   cd: 'where',
   path: 'where',
   run: 'exec',
+  skills: 'skill',
   remove: 'rm',
   'self-update': 'upgrade',
 };
@@ -115,6 +118,7 @@ ${c.bold('Commands')}
   ${c.cyan('exec')}       run one command in every repo
   ${c.cyan('manifest')}   push or pull the catalogue through a private gist
   ${c.cyan('doctor')}     check git, SSH, GitHub auth and workspace health
+  ${c.cyan('skill')}      install the skill that lets your coding agent drive talea
   ${c.cyan('upgrade')}    update the CLI itself
 
 ${c.bold('A new machine')}
@@ -130,6 +134,9 @@ ${c.bold('Every day')}
   talea sync                    ${c.dim('# clone the new, fast-forward the rest')}
   talea status --drift          ${c.dim('# what is not where I left it')}
 
+${c.bold('With an agent')}
+  talea skill install           ${c.dim('# then ask Claude Code "where is eklavya?"')}
+
 ${c.bold('Common options')}
   -g, --group <names>   restrict to groups, e.g. -g nonstopio
   -r, --repo <names>    restrict to repos, e.g. -r eklavya

package/src/commands/add.js

@@ -54,7 +54,7 @@ export function resolve(manifest, name) {
 }
 
 export async function run(opts, positionals = []) {
-  const { root, manifest, state } = requireWorkspace();
+  const { root, manifest, state } = await requireWorkspace();
   requireCatalogue(manifest);
 
   if (!positionals.length) {

package/src/commands/adopt.js

@@ -322,7 +322,7 @@ export function parseFromPaths(from) {
 }
 
 export async function run(opts) {
-  const { root, manifest, state } = requireWorkspace();
+  const { root, manifest, state } = await requireWorkspace();
 
   if (opts['fix-paths']) {
     heading('Repairing paths for repos already adopted');

package/src/commands/clone.js

@@ -200,7 +200,7 @@ export function writeDocs(manifest, root, repos) {
 }
 
 export async function run(opts) {
-  const { root, manifest, state } = requireWorkspace();
+  const { root, manifest, state } = await requireWorkspace();
   requireCatalogue(manifest);
 
   const protocol = opts.protocol ?? state.protocol ?? 'ssh';

package/src/commands/exec.js

@@ -46,7 +46,7 @@ export async function run(opts, positionals) {
     process.exit(1);
   }
 
-  const { root, manifest, state } = requireWorkspace();
+  const { root, manifest, state } = await requireWorkspace();
   const pool = opts.all ? manifest.repos : machineRepos(manifest, state);
   const entries = clonedOnly(withPaths(manifest, root, selectRepos(manifest, opts, pool)));
 

package/src/commands/init.js

@@ -7,17 +7,15 @@ import {
   STATE_FILE,
   expandHome,
   findWorkspace,
-  groupDir,
   loadManifest,
-  loadState,
   repoGroup,
   saveState,
 } from '../config.js';
 import { samePath } from '../adopt.js';
-import { machineRepos } from '../workspace.js';
 import { c, context, fail, heading, info, ok, plain, skip, warn } from '../log.js';
 import { run as discover } from './discover.js';
 import { run as sync } from './sync.js';
+import { rememberWorkspace } from '../workspace.js';
 
 export const help = `
 ${c.bold('talea init')} — set this machine up
@@ -108,6 +106,8 @@ export async function run(opts, positionals = []) {
   } else {
     skip(`${STATE_FILE} already here, leaving it alone`);
   }
+  // So `talea sync` run from outside any workspace knows this one exists.
+  rememberWorkspace(target);
 
   let manifest = loadManifest(target);
 
@@ -129,13 +129,13 @@ export async function run(opts, positionals = []) {
     ['groups', `${groups.length}`],
   ]);
 
-  // The group folders for the repos this machine will actually hold — not one
-  // per owner in the catalogue. A collaborator repo you never clone should not
-  // leave an empty folder in the tree forever.
-  const mine = machineRepos(manifest, loadState(target));
-  for (const g of new Set(mine.map((r) => repoGroup(r)))) {
-    mkdirSync(path.join(target, groupDir(manifest, g)), { recursive: true });
-  }
+  // No group folders are created here. `init` runs before the picker — the
+  // checklist lives in `sync` — so anything made at this point is made from the
+  // catalogue's defaults, which is every owner the discovery found. Picking
+  // four repos out of 228 then left 18 empty owner folders in the tree, and an
+  // empty folder is indistinguishable from a checkout somebody deleted.
+  // `cloneMissing` creates the parent of each repo it is about to clone, so the
+  // only folders that ever appear are the ones with something in them.
 
   if (opts.clone === false) {
     plain(`\n${c.dim('Workspace ready. Run `talea sync` when you want the repos.')}`);

package/src/commands/select.js

@@ -48,7 +48,7 @@ export function changes(before, after) {
 }
 
 export async function run(opts) {
-  const { root, manifest, state } = requireWorkspace();
+  const { root, manifest, state } = await requireWorkspace();
   requireCatalogue(manifest);
 
   // -g/-r narrow a run; they cannot narrow a decision about the whole machine.

package/src/commands/skill.js

@@ -0,0 +1,142 @@
+// `talea skill` — put the agent-facing skill in the user's Claude Code.
+//
+// The skill is a single Markdown file describing how to drive this CLI safely:
+// which commands read, which move things, and which two flags must never be
+// reached for on somebody's behalf. Installing it at **user scope**
+// (`~/.claude/skills/`) rather than in a repo is the point — the developer has
+// one workspace across every project, so the agent needs the same instructions
+// in all of them.
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { c, fail, heading, info, ok, plain, warn } from '../log.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+/** The copy that ships in the package. */
+export const source = path.join(here, '..', '..', 'skills', 'talea', 'SKILL.md');
+
+/**
+ * Claude Code reads user-scope skills from `~/.claude/skills/<name>/SKILL.md`.
+ * `CLAUDE_CONFIG_DIR` is how somebody moves that directory, and honouring it is
+ * the difference between installing the skill and installing it somewhere
+ * nothing will ever read it.
+ */
+export const target = () =>
+  path.join(
+    process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'),
+    'skills',
+    'talea',
+    'SKILL.md',
+  );
+
+/**
+ * The marker that says a file at that path is ours.
+ *
+ * Somebody may already have their own skill called `talea`. Overwriting it
+ * would destroy work this tool has no claim on, so the only file `install`
+ * will replace is one carrying this line, and the only file `uninstall` will
+ * delete is the same.
+ */
+const MARK = '<!-- talea-skill:';
+
+export const isOurs = (file) => {
+  try {
+    return readFileSync(file, 'utf8').includes(MARK);
+  } catch {
+    return false;
+  }
+};
+
+export const help = `
+${c.bold('talea skill')} — teach your coding agent to drive talea
+
+  ${c.dim('talea skill')}             is it installed, and where
+  ${c.dim('talea skill install')}     copy it into ~/.claude/skills/talea/
+  ${c.dim('talea skill uninstall')}   take it back out
+
+Installs at ${c.bold('user scope')}, so every project you open gets it — your workspace
+spans all of them, and the agent needs the same instructions in each.
+
+The skill is what turns ${c.dim('"where is eklavya?"')} and ${c.dim('"tidy up my repos"')} into the
+right talea command, with the guardrails attached: an adopt is always dry-run
+first, ${c.dim('--loose')} is never taken on your behalf, and nothing is ever deleted.
+
+It refuses to overwrite a skill called ${c.dim('talea')} that this tool did not write.
+Move yours first if you have one.
+`;
+
+export function run(opts, positionals = []) {
+  const action = positionals[0] ?? 'status';
+  const dest = target();
+
+  if (action === 'status') return status(dest);
+  if (action === 'install') return install(dest);
+  if (action === 'uninstall' || action === 'remove') return uninstall(dest);
+
+  fail(`Unknown: talea skill ${action}`);
+  plain(`\n  Try ${c.dim('talea skill install')}, ${c.dim('talea skill uninstall')}, or ${c.dim('talea skill')} on its own.`);
+  // `process.exitCode`, not `process.exit()` — the same contract `summary()`
+  // uses, and the only one a test can drive without taking the runner down.
+  process.exitCode = 1;
+}
+
+function status(dest) {
+  heading('talea skill');
+  if (!existsSync(dest)) {
+    warn('Not installed.');
+    plain(`\n  ${c.dim('talea skill install')}   put it in ${c.bold(dest)}`);
+    return;
+  }
+  if (!isOurs(dest)) {
+    warn(`Something else owns ${c.bold(dest)}.`);
+    plain(`\n  It is not a file talea wrote, so talea will not touch it.`);
+    return;
+  }
+  const same = readFileSync(dest, 'utf8') === readFileSync(source, 'utf8');
+  ok(`Installed at ${c.bold(dest)}`);
+  if (!same) {
+    plain(`\n  ${c.yellow('Out of date')} — ${c.dim('talea skill install')} rewrites it from this version.`);
+  }
+}
+
+function install(dest) {
+  heading('talea skill install');
+
+  if (existsSync(dest) && !isOurs(dest)) {
+    // Somebody's own skill, under the name we want. Never overwrite it: it is
+    // work this tool has no claim on, and there is no undo.
+    fail(`There is already a skill called "talea" at ${c.bold(dest)}, and talea did not write it.`);
+    plain(`\n  Move it somewhere else first, then run this again. Nothing has been changed.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  mkdirSync(path.dirname(dest), { recursive: true });
+  copyFileSync(source, dest);
+  ok(`Installed ${c.bold(dest)}`);
+  info(`Restart Claude Code to pick it up — skills are read at session start.`);
+  plain(`\n  Then ${c.dim('"where is eklavya?"')} or ${c.dim('"sync my repos"')} reaches the right command on its own.`);
+}
+
+function uninstall(dest) {
+  heading('talea skill uninstall');
+
+  if (!existsSync(dest)) {
+    info('Nothing to remove.');
+    return;
+  }
+  if (!isOurs(dest)) {
+    fail(`${c.bold(dest)} is not a file talea wrote — leaving it alone.`);
+    process.exitCode = 1;
+    return;
+  }
+  rmSync(dest, { force: true });
+  // The directory is ours too, and an empty one left behind shows up in
+  // `/skills` as a skill with no file.
+  rmSync(path.dirname(dest), { recursive: true, force: true });
+  ok(`Removed ${c.bold(dest)}`);
+}

package/src/commands/status.js

@@ -29,7 +29,7 @@ Options
 `;
 
 export async function run(opts) {
-  const { root, manifest, state } = requireWorkspace();
+  const { root, manifest, state } = await requireWorkspace();
   const pool = opts.all ? manifest.repos : machineRepos(manifest, state);
   const entries = withPaths(manifest, root, selectRepos(manifest, opts, pool));
 

package/src/commands/sync.js

@@ -31,6 +31,9 @@ your default set, or a checklist of everything in the catalogue with those
 defaults already ticked. The answer is remembered in ${c.dim('.talea.json')}, so every run
 after that is a bare ${c.dim('talea sync')}.
 
+It runs from anywhere. Inside a workspace it uses that one; outside, it uses
+the workspace ${c.dim('talea init')} made, or asks which when this machine has several.
+
 Options
   -g, --group <names>   comma-separated groups
   -r, --repo <names>    comma-separated repo names
@@ -53,7 +56,7 @@ leaves it alone, and says which.
 `;
 
 export async function run(opts) {
-  const { root, manifest, state } = requireWorkspace();
+  const { root, manifest, state } = await requireWorkspace();
   requireCatalogue(manifest);
 
   const protocol = opts.protocol ?? state.protocol ?? 'ssh';

package/src/commands/tree.js

@@ -30,8 +30,8 @@ Options
 
 const hasDoc = (dir) => existsSync(path.join(dir, 'CLAUDE.md'));
 
-export function run(opts) {
-  const { root, manifest, state } = requireWorkspace();
+export async function run(opts) {
+  const { root, manifest, state } = await requireWorkspace();
   const pool = opts.all ? manifest.repos : machineRepos(manifest, state);
   const entries = withPaths(manifest, root, selectRepos(manifest, opts, pool));
 

package/src/commands/where.js

@@ -17,10 +17,13 @@ composes with ${c.dim('cd')}, ${c.dim('code')}, ${c.dim('open')} and anything el
 
 Exits non-zero if the repo is not in the catalogue, so ${c.dim('cd $(talea where typo)')}
 fails loudly instead of landing you in your home directory.
+
+Works from outside a workspace too: with one on this machine it uses that, with
+several it asks — on stderr, so the answer never ends up in the path.
 `;
 
-export function run(opts, positionals = []) {
-  const { root, manifest } = requireWorkspace();
+export async function run(opts, positionals = []) {
+  const { root, manifest } = await requireWorkspace();
   const name = positionals[0];
 
   if (!name) {

package/src/config.js

@@ -33,7 +33,7 @@ export const USER_STATE = path.join(USER_DIR, 'state.json');
 
 const readJson = (file) => JSON.parse(readFileSync(file, 'utf8'));
 
-/** Machine-wide state: the update-check stamp, the gist id. Not per workspace. */
+/** Machine-wide state: the update-check stamp, the gist id, the workspace list. Not per workspace. */
 export function readUserState() {
   try {
     return readJson(USER_STATE);
@@ -48,7 +48,8 @@ export function writeUserState(state) {
     writeFileSync(USER_STATE, JSON.stringify(state, null, 2) + '\n');
   } catch {
     // A read-only home directory must not break the actual command. The only
-    // things kept here are a cache stamp and a gist id.
+    // things kept here are a cache stamp, a gist id and the workspace list,
+    // and a lost list re-fills itself the next time a command runs inside one.
   }
 }
 
@@ -95,6 +96,19 @@ export function findWorkspace(start = process.cwd()) {
   }
 }
 
+/**
+ * Every workspace this machine has set up, as recorded in ~/.talea/state.json.
+ *
+ * This is what lets `talea sync` run from anywhere: outside a workspace the
+ * upward walk finds nothing, and this list is what is left to ask. Kept in the
+ * machine-wide state rather than the catalogue because a path on this laptop
+ * means nothing on the next one. Entries whose .talea.json has gone are skipped
+ * on read, not dropped on write — a deleted workspace stops being offered, but
+ * an unplugged drive that comes back has not been forgotten.
+ */
+export const knownWorkspaces = () =>
+  (readUserState().workspaces ?? []).filter((dir) => existsSync(path.join(dir, STATE_FILE)));
+
 export function loadState(workspaceRoot) {
   const file = path.join(workspaceRoot, STATE_FILE);
   return existsSync(file) ? readJson(file) : {};

package/src/theme.js

@@ -24,18 +24,23 @@ export const useColor =
 // fallback and uses it whenever COLORTERM is not set.
 const trueColor = /^(truecolor|24bit)$/i.test(process.env.COLORTERM ?? '');
 
-// ── Phosphor palette ───────────────────────────────────────────
-// [24-bit hex, basic-16 SGR code]. The basic code is what a terminal without
-// COLORTERM gets; it is deliberately the closest *readable* match rather than
-// the closest numerically — `faint` has no bright equivalent, so it falls back
-// to grey rather than a green nobody can read on a light background.
+// ── Verdigris palette ──────────────────────────────────────────
+// [24-bit hex, basic-16 SGR code]. The same accent ramp the website is built
+// on — verdigris, new growth on aged bronze — so the CLI and talea.run are one
+// product rather than two that share a name. The hexes are the `--vd-*` steps in
+// `web/public/tokens.css`; change one and change the other.
+//
+// The basic code is what a terminal without COLORTERM gets. It is deliberately
+// the closest *readable* match rather than the closest numerically — `faint`
+// has no bright equivalent, so it falls back to grey rather than a teal nobody
+// can read on a light background.
 const PALETTE = {
-  green: ['#39ff14', 92], // hot phosphor — something worked
-  aged: ['#1f8a3b', 32], // settled green — a branch, a path, a detail
-  faint: ['#0e3b1c', 90], // barely lit — rules and fills
-  amber: ['#ffb000', 33], // attention, but not a failure
-  red: ['#ff3b30', 31], // failure
-  bone: ['#d6dbd6', 37], // plain text that still wants to be lit
+  green: ['#79D5C4', 96], // --vd-300, the accent — something worked
+  aged: ['#199688', 36], // --vd-500 — a branch, a path, a detail
+  faint: ['#07403C', 90], // --vd-800 — rules and fills
+  amber: ['#E8920C', 33], // --warning: attention, but not a failure
+  red: ['#E5484D', 31], // --error: failure
+  bone: ['#EAE7E1', 37], // --ink: plain text that still wants to be lit
 };
 
 

package/src/workspace.js

@@ -4,9 +4,25 @@
 // Every command that acts on repos goes through here, so `clone`, `sync`,
 // `status` and `exec` filter identically.
 
-import { findWorkspace, loadManifest, loadState, repoDir, repoGroup } from './config.js';
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+
+import { samePath } from './adopt.js';
+import {
+  STATE_FILE,
+  findWorkspace,
+  knownWorkspaces,
+  loadManifest,
+  loadState,
+  readUserState,
+  repoDir,
+  repoGroup,
+  writeUserState,
+} from './config.js';
 import { isRepo } from './git.js';
-import { fail } from './log.js';
+import { c, fail } from './log.js';
 
 const csv = (v) =>
   (Array.isArray(v) ? v : [v])
@@ -16,16 +32,87 @@ const csv = (v) =>
     .filter(Boolean);
 
 /**
- * Resolve the workspace, manifest and state, or exit with a useful message.
- * Commands that need an initialised workspace call this first.
+ * Add a workspace to this machine's list, once.
+ *
+ * Compared with samePath, not as strings: on macOS and Windows `~/workspace`
+ * and `~/Workspace` are one folder, and cd-ing in with the other spelling would
+ * otherwise add it again on every run.
+ */
+export function rememberWorkspace(root) {
+  const state = readUserState();
+  const list = state.workspaces ?? [];
+  if (list.some((dir) => samePath(dir, root))) return;
+  writeUserState({ ...state, workspaces: [...list, root] });
+}
+
+/**
+ * The workspaces a command run from outside any of them could mean: every one
+ * `init` has recorded, plus the default `~/Workspace` — which is how a
+ * workspace made before the list existed is still found from anywhere.
  */
-export function requireWorkspace() {
-  const root = findWorkspace();
-  if (!root) {
+export function workspaceCandidates(known = knownWorkspaces(), manifest = loadManifest(null)) {
+  const fallback = path.join(os.homedir(), manifest.workspace || 'Workspace');
+  const all = existsSync(path.join(fallback, STATE_FILE)) ? [...known, fallback] : known;
+  return all.filter((dir, i) => all.findIndex((d) => samePath(d, dir)) === i);
+}
+
+/**
+ * Outside a workspace: one known workspace is used, several are asked about.
+ *
+ * Everything here goes to stderr — `cd $(talea where)` reads stdout, and a
+ * prompt or a note there is a folder the shell tries to enter. With no
+ * terminal to ask on, it stops rather than picks: a script that syncs whichever
+ * workspace happened to be first is running against a tree nobody named.
+ */
+async function pickKnownWorkspace() {
+  const found = workspaceCandidates();
+
+  if (!found.length) {
     fail('Not inside a talea workspace (no .talea.json found).');
     console.error('\n  Run `talea init` to create one, or cd into an existing workspace.');
     process.exit(1);
   }
+  if (found.length === 1) {
+    console.error(c.dim(`Using the workspace at ${found[0]}\n`));
+    return found[0];
+  }
+  if (!process.stdin.isTTY || !process.stderr.isTTY) {
+    fail(`Not inside a talea workspace, and this machine has ${found.length}.`);
+    for (const dir of found) console.error(`    ${c.bold(dir)}`);
+    console.error('\n  cd into the one you mean.');
+    process.exit(1);
+  }
+
+  console.error(`\n${c.bold('Which workspace?')}`);
+  found.forEach((dir, i) => console.error(`  ${c.cyan(String(i + 1))}  ${dir}`));
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  const answer = (await rl.question(`\n${c.dim(`[1-${found.length}]`)} `)).trim();
+  rl.close();
+
+  // A wrong answer stops, same as a typo'd repo name: guessing here would run
+  // a bulk command against a tree the developer did not choose.
+  const chosen = found[Number(answer) - 1];
+  if (!/^\d+$/.test(answer) || !chosen) {
+    fail(`"${answer}" is not one of 1-${found.length}.`);
+    process.exit(1);
+  }
+  console.error('');
+  return chosen;
+}
+
+/**
+ * Resolve the workspace, manifest and state, or exit with a useful message.
+ * Commands that need an initialised workspace call this first.
+ *
+ * Inside a workspace the upward walk wins, exactly as git's does. Outside one,
+ * the workspaces this machine knows about are offered instead.
+ */
+export async function requireWorkspace() {
+  const inside = findWorkspace();
+  // Recorded on every run from inside, so a workspace made before the list
+  // existed joins it the first time anything is run there.
+  if (inside) rememberWorkspace(inside);
+  const root = inside ?? (await pickKnownWorkspace());
   const manifest = loadManifest(root);
   const state = loadState(root);
   return { root, manifest, state };