@nemus-cli/nemus 0.2.4 → 0.2.5

package/skills/nemus/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: nemus
+description: Manage multi-repo development workspaces — create, sync, branch, diff, clone, archive, analyze dependencies, run commands across repos, check status, clean up, delete, list org repos, search repos, list suites, remove repo, cache, suite management, sessions, history, generate docs, configure, MCP server, AI prompt. Use when working with workspaces, repos, branches, git operations across multiple repos, or the `nemus` CLI tool. NEVER use `git clone` directly — always use `nemus update` to add repos and `nemus create` to create workspaces.
+bashPattern: "\\bnemus\\s+(create|list|update|delete|sync|status|diff|run|go|doctor|analyze-deps|history|cleanup|remove-repo|archive|sessions|generate-docs|configure|configure-claude|ghq-status|tui|dashboard|dash|branch|suite|cache|mcp|--)\\b"
+---
+
+# Nemus
+
+Manage multi-repo workspaces with the `nemus` CLI (alias `nem`). Every command has `--help`.
+
+> **Rules — do not break these:**
+> - **Never** `git clone` to add a repo or create a workspace — use `nemus create` / `nemus update`. Direct git bypasses workspace metadata and breaks `nemus status`/`sync`.
+> - **Never** `git worktree` for a second checkout — worktrees are invisible to `nemus`. Add another instance with `nemus update --repos <repo>:<suffix>` (clones into `<repo>-<suffix>`, tracked independently).
+> - **Only read code from repos in the CURRENT workspace.** Need another repo? Add it with `nemus update --repos <repo>` and read it here — never read from another workspace or a global clone path (they may be stale/on other branches).
+
+## Usage
+
+Commands are options-first with an interactive fallback: pass flags to run non-interactively; omit them (with a TTY) to be prompted. `--yes`/`-y` skips confirmations and the post-create agent launch.
+
+```bash
+nemus create --workspace payments --repos partnerships-api,payments-db --yes   # non-interactive
+nemus create                                                                    # fully interactive
+```
+
+Global flags: `-f/--force-refresh` (skip repo cache), `-y/--yes` (skip prompts), `-V/--version`, `-h/--help`.
+
+## Command Reference
+
+### Core Workspace Lifecycle
+
+| Intent | Reference | CLI | Alias |
+|---|---|---|---|
+| Create new workspace | [create-workspace](references/create-workspace.md) | `nemus create` | `c` |
+| Add repos to workspace | [update-workspace](references/update-workspace.md) | `nemus update` | `u` |
+| Delete workspace permanently | [delete-workspace](references/delete-workspace.md) | `nemus delete` | `d` |
+| Archive / unarchive workspace | [archive-workspace](references/archive-workspace.md) | `nemus archive` | `a` |
+| List all workspaces | [list-workspaces](references/list-workspaces.md) | `nemus list` | `l` |
+| Navigate to workspace | [go](references/go.md) | `nemus go [name]` | — |
+
+### Status & Operations
+
+| Intent | Reference | CLI | Alias |
+|---|---|---|---|
+| Git status across repos | [workspace-status](references/workspace-status.md) | `nemus status [name]` | `st` |
+| Pull latest (git sync) | [workspace-sync](references/workspace-sync.md) | `nemus sync [name]` | `s` |
+| Show diff summary | [workspace-diff](references/workspace-diff.md) | `nemus diff [name]` | `di` |
+| Run shell command across repos | [run-command](references/run-command.md) | `nemus run [name] <cmd>` | `r` |
+| Health check | [workspace-doctor](references/workspace-doctor.md) | `nemus doctor [name]` | `doc` |
+| Clean node_modules / artifacts | [workspace-cleanup](references/workspace-cleanup.md) | `nemus cleanup <name>` | `cl` |
+| Remove repo from workspace | [remove-repo](references/remove-repo.md) | `nemus remove-repo` | `rr` |
+| Analyze inter-repo deps | [analyze-deps](references/analyze-deps.md) | `nemus analyze-deps [name]` | `ad` |
+| Generate docs for workspace | [generate-docs](references/generate-docs.md) | `nemus generate-docs [name]` | `gd` |
+
+### Branch Management
+
+| Intent | Reference | CLI |
+|---|---|---|
+| Switch branch across repos | [switch-branch](references/switch-branch.md) | `nemus branch switch` |
+| Create branch across repos | [branch-create](references/branch-create.md) | `nemus branch create` |
+| Merge branches across repos | [branch-merge](references/branch-merge.md) | `nemus branch merge <ws> <src> <tgt>` |
+| Rebase branches across repos | [branch-rebase](references/branch-rebase.md) | `nemus branch rebase <ws> <base>` |
+
+### Suites (Reusable Repo Collections)
+
+| Intent | Reference | CLI |
+|---|---|---|
+| List saved suites | [list-suites](references/list-suites.md) | `nemus suite list` |
+| Create a suite | [suite-create](references/suite-create.md) | `nemus suite create` |
+| Delete a suite | [suite-delete](references/suite-delete.md) | `nemus suite delete` |
+| Export suite(s) to JSON | [suite-export](references/suite-export.md) | `nemus suite export [file]` |
+| Import suite(s) from JSON | [suite-import](references/suite-import.md) | `nemus suite import <file>` |
+| Create workspace from suite | [suite-use](references/suite-use.md) | `nemus suite use` |
+
+### Cache & Repo Discovery
+
+| Intent | Reference | CLI |
+|---|---|---|
+| Search org repos | [search-repos](references/search-repos.md) | `nemus cache search <query>` |
+| List all org repos | [list-org-repos](references/list-org-repos.md) | `nemus cache list` |
+| View cache statistics | [cache-info](references/cache-info.md) | `nemus cache info` |
+| Refresh repo cache | [update-cache](references/update-cache.md) | `nemus cache refresh` |
+| Clear cache | [cache-clear](references/cache-clear.md) | `nemus cache clear` |
+
+### Sessions & History
+
+| Intent | Reference | CLI | Alias |
+|---|---|---|---|
+| Resume Claude session | [sessions](references/sessions.md) | `nemus sessions` | `ses` |
+| Agent management dashboard | [dashboard](references/dashboard.md) | `nemus dashboard` | `dash` |
+| View operation history | [history](references/history.md) | `nemus history` | `h` |
+
+### Configuration & MCP
+
+| Intent | Reference | CLI |
+|---|---|---|
+| Configure Nemus | [configure](references/configure.md) | `nemus configure` |
+| Configure Claude integration | [configure-claude](references/configure-claude.md) | `nemus configure-claude` |
+| Check ghq status | [ghq-status](references/ghq-status.md) | `nemus ghq-status` |
+| Install / manage MCP server | [mcp](references/mcp.md) | `nemus mcp install\|status\|upgrade\|uninstall` |
+
+### AI Assistant & TUI
+
+| Intent | Reference | CLI |
+|---|---|---|
+| Natural-language workspace management | [ai-prompt](references/ai-prompt.md) | `nemus -- <prompt>` |
+| Full interactive terminal UI | — | `nemus tui` |
+
+## Routing
+
+Match the user's intent to a row above and read that reference before running commands. If no reference exists, use `nemus <command> --help`. All repo management must go through `nemus` so metadata and context files stay in sync.

package/skills/{workspace-manager → nemus}/references/ai-prompt.md

@@ -32,12 +32,6 @@ nemus -- "Set up a workspace for the billing migration"
 - Claude Code CLI must be installed (`claude` command available)
 - MCP server should be installed (`nemus mcp install`)
 
-## When to Suggest
-
-- User wants to manage workspaces conversationally
-- User describes a complex workspace setup in natural language
-- User is new to the CLI and prefers natural language
-
 ## Notes
 
 - The shell integration treats `nemus --` as a create-like command — if a workspace is created, it auto-CDs into it.

package/skills/{workspace-manager → nemus}/references/analyze-deps.md

@@ -32,14 +32,3 @@ nemus analyze-deps
 - **Mermaid diagram** — visual dependency graph
 - Optionally saves analysis to workspace metadata
 
-## Suggested Follow-ups
-
-- Missing dependencies: `nemus update --workspace <name> --repos <missing>` to add them
-- Circular dependencies: explain resolution strategies
-- For documentation: `nemus generate-docs <name>` to include the dependency graph
-
-## Success Criteria
-
-- Dependency analysis is presented with per-repo dependency lists.
-- Circular dependencies are highlighted if detected.
-- Missing repos are identified.

package/skills/{workspace-manager → nemus}/references/archive-workspace.md

@@ -27,12 +27,3 @@ nemus list --archived
 | `--yes` | `-y` | Skip confirmation prompt |
 | `--unarchive` | | Restore instead of archive |
 
-## When to Suggest
-
-- Suggest archiving instead of deleting when the user may need the workspace later.
-- Suggest unarchiving when the user asks about a workspace that was recently archived.
-
-## Success Criteria
-
-- Workspace is hidden from default `nemus list` results.
-- User is aware of the 30-day auto-delete policy.

package/skills/{workspace-manager → nemus}/references/branch-create.md

@@ -26,6 +26,3 @@ nemus branch create <workspace> <branch-name> --base <base-branch> --force
 
 After creation, run `nemus status <name>` to verify all repos are on the new branch.
 
-## Success Criteria
-
-- New branch is created in all repos and per-repo results are reported.

package/skills/{workspace-manager → nemus}/references/branch-merge.md

@@ -16,7 +16,3 @@ Merge a source branch into a target branch across all repositories in a workspac
 
 3. If there are merge conflicts, suggest the user resolve them manually in the affected repos.
 
-## Success Criteria
-
-- Merge is attempted in all repos.
-- Results are reported per repo with success/failure status.

package/skills/{workspace-manager → nemus}/references/branch-rebase.md

@@ -16,7 +16,3 @@ Rebase all repositories in a workspace onto a target branch.
 
 3. If there are rebase conflicts, suggest the user resolve them manually in the affected repos.
 
-## Success Criteria
-
-- Rebase is attempted in all repos.
-- Results are reported per repo with success/failure status.

package/skills/{workspace-manager → nemus}/references/cache-clear.md

@@ -13,6 +13,3 @@ Clear the local GitHub repository cache. A new cache will be created automatical
 
 3. Suggest `nemus cache refresh` if the user wants to immediately rebuild the cache.
 
-## Success Criteria
-
-- Cache is cleared successfully.

package/skills/{workspace-manager → nemus}/references/cache-info.md

@@ -17,6 +17,3 @@ View cache statistics including repo count, age, and size.
 
 3. If cache is stale or missing, suggest `nemus cache refresh`.
 
-## Success Criteria
-
-- Cache statistics are displayed.

package/skills/{workspace-manager → nemus}/references/configure-claude.md

@@ -26,6 +26,3 @@ w cc
 - The `.claude.md` file provides workspace context to Claude Code sessions.
 - Auto-launch requires the Claude Code CLI to be installed.
 
-## Success Criteria
-
-- Claude integration settings are updated.

package/skills/{workspace-manager → nemus}/references/configure.md

@@ -1,6 +1,6 @@
 # Configure
 
-Configure workspace-manager global settings interactively.
+Configure Nemus global settings interactively.
 
 ## Instructions
 
@@ -30,6 +30,3 @@ w cfg
 - Enabling MCP after disabling it triggers an automatic install.
 - This is interactive-only — there are no non-interactive flags.
 
-## Success Criteria
-
-- User's settings are saved to `~/.nemus/config.json`.

package/skills/{workspace-manager → nemus}/references/create-workspace.md

@@ -39,7 +39,3 @@ nemus create --workspace payments --repos partnerships-api,payments-db --yes
 nemus suite use --suite platform --workspace platform-ws --yes
 ```
 
-## Success Criteria
-
-- Workspace directory exists with all requested repos cloned.
-- User is informed of the workspace path and suggested next steps.

package/skills/{workspace-manager → nemus}/references/dashboard.md

@@ -55,7 +55,3 @@ Opens a tmux session with a sidebar showing active agents and their status. Agen
 - Session resume picker (`s`) with fuzzy search
 - Auto-installs Claude hooks on first run
 
-## Success Criteria
-
-- Tmux dashboard opens with sidebar and agent panes.
-- Agents can be launched, monitored, focused, zoomed, and killed from the dashboard.

package/skills/{workspace-manager → nemus}/references/delete-workspace.md

@@ -27,7 +27,3 @@ Permanently delete one or more workspaces and all their cloned repositories.
 | `--workspace <name>` | `-w` | Workspace name(s), comma-separated for multiple |
 | `--yes` | `-y` | Skip confirmation prompt |
 
-## Success Criteria
-
-- Workspace directory and all cloned repos are removed from disk.
-- User received explicit confirmation before deletion (unless `--yes` was passed).

package/skills/{workspace-manager → nemus}/references/generate-docs.md

@@ -25,12 +25,3 @@ Creates these files in the workspace root:
 - `DEPENDENCY-GRAPH.md` — Mermaid diagram of inter-repo dependencies
 - `REPOSITORY-INDEX.md` — Detailed index of all repos
 
-## When to Suggest
-
-- After creating a workspace with many repos
-- When user wants to understand workspace structure
-- When onboarding someone to a multi-repo project
-
-## Success Criteria
-
-- All three documentation files are generated in the workspace directory.

package/skills/{workspace-manager → nemus}/references/ghq-status.md

@@ -21,8 +21,3 @@ nemus ghq-status
 3. **Subsequent clones**: Much faster (local copy vs network clone)
 4. **Isolation**: Each workspace still gets its own independent clone
 
-## When to Suggest
-
-- User reports slow workspace creation
-- User asks about optimizing clone performance
-- User asks what ghq is or whether to install it

package/skills/{workspace-manager → nemus}/references/go.md

@@ -27,7 +27,3 @@ The `nemgo` variant also launches Claude Code automatically if a session exists.
 2. The shell integration function reads that file and runs `cd`
 3. If the workspace has an existing Claude session, it resumes it
 
-## Success Criteria
-
-- The terminal's working directory changes to the workspace path.
-- If a Claude session exists, it resumes automatically (with `nemgo`).

package/skills/{workspace-manager → nemus}/references/history.md

@@ -1,6 +1,6 @@
 # History
 
-View operation history for workspace-manager commands.
+View operation history for Nemus commands.
 
 ## Instructions
 
@@ -35,7 +35,3 @@ w h              # same as nemus history
 w h stats        # same as nemus history stats
 ```
 
-## Success Criteria
-
-- History records are displayed in a table with timestamp, command, workspace, duration, and status.
-- Stats show meaningful aggregations.

package/skills/{workspace-manager → nemus}/references/list-org-repos.md

@@ -20,7 +20,3 @@ List all organization repositories from GitHub.
 
 3. If the cache is stale, suggest `nemus cache refresh` to update it.
 
-## Success Criteria
-
-- All org repos are listed, optionally grouped by prefix.
-- User is guided toward `nemus cache search` if the list is too large to browse.

package/skills/{workspace-manager → nemus}/references/list-suites.md

@@ -15,7 +15,3 @@ To create a workspace from a suite (non-interactive):
 nemus suite use --suite <suite-name> --workspace <workspace-name> --yes
 ```
 
-## Success Criteria
-
-- All available suites are listed with their repo counts and descriptions.
-- User is guided toward `nemus suite use` if they want to create a workspace from a suite.

package/skills/{workspace-manager → nemus}/references/list-workspaces.md

@@ -1,6 +1,6 @@
 # List Workspaces
 
-List all existing workspaces managed by workspace-manager.
+List all existing workspaces managed by Nemus.
 
 ## Instructions
 
@@ -21,7 +21,3 @@ List all existing workspaces managed by workspace-manager.
 
 3. If no workspaces exist, suggest creating one with `nemus create`.
 
-## Success Criteria
-
-- All active workspaces are listed with repo count and creation date.
-- Archived workspaces are shown only when explicitly requested.

package/skills/{workspace-manager → nemus}/references/mcp.md

@@ -6,7 +6,7 @@ Manage the MCP (Model Context Protocol) server integration with Claude Code.
 
 ### Install
 
-Register the workspace-manager MCP server with Claude Code:
+Register the Nemus MCP server with Claude Code:
 ```bash
 nemus mcp install
 ```
@@ -27,7 +27,7 @@ Update hooks and skills without re-registering the MCP server:
 nemus mcp upgrade
 ```
 
-Use after updating the workspace-manager package.
+Use after updating the Nemus package.
 
 ### Status
 
@@ -38,12 +38,7 @@ nemus mcp status
 
 ## What MCP Provides
 
-When installed, Claude Code gains access to workspace-manager tools:
+When installed, Claude Code gains access to Nemus tools:
 - `create-workspace`, `list-workspaces`, `workspace-status`, etc.
 - Enables natural language workspace management via `nemus -- <prompt>`
 
-## When to Suggest
-
-- After installing or upgrading workspace-manager
-- When Claude Code doesn't seem to have workspace tools
-- When `nemus -- <prompt>` fails to find MCP tools

package/skills/{workspace-manager → nemus}/references/remove-repo.md

@@ -21,6 +21,3 @@ Remove a repository instance from a workspace.
 | `--repos <dir,...>` | `-r` | Comma-separated directory names to remove |
 | `--yes` | `-y` | Skip confirmation prompt |
 
-## Success Criteria
-
-- The specified repo directory is removed from the workspace after user confirmation.

package/skills/{workspace-manager → nemus}/references/run-command.md

@@ -10,7 +10,7 @@ nemus run <workspace> <command>
 
 Alias:
 ```bash
-w r <workspace> <command>
+nem r <workspace> <command>
 ```
 
 Without a workspace name, prompts interactively:
@@ -38,7 +38,3 @@ Shows per-repo results:
 
 Exits with code 1 if any repo failed.
 
-## Success Criteria
-
-- Command is executed in all repos and per-repo success/failure is reported.
-- stdout and stderr from each repo are clearly displayed.

package/skills/{workspace-manager → nemus}/references/search-repos.md

@@ -18,7 +18,3 @@ Search organization repositories by name or description using fuzzy matching.
    - `nemus create` to create a new workspace with selected repos
    - `nemus update` to add repos to an existing workspace
 
-## Success Criteria
-
-- Matching repos are listed with name, description, and URL.
-- Follow-up action (create or update workspace) is suggested if appropriate.

package/skills/{workspace-manager → nemus}/references/sessions.md

@@ -20,8 +20,3 @@ w ses
 2. Shows them sorted by last active time
 3. User picks one → terminal CDs to that workspace and resumes the Claude session
 
-## When to Suggest
-
-- User asks to "continue where I left off"
-- User wants to resume work on a previous workspace
-- User asks about their recent Claude sessions

package/skills/{workspace-manager → nemus}/references/suite-create.md

@@ -16,7 +16,3 @@ Create a new suite (reusable collection of repositories) that can be used to qui
 
 3. After creation, confirm with the suite name and repo count.
 
-## Success Criteria
-
-- Suite is saved with the specified name and repos.
-- Suite appears in `nemus suite list`.

package/skills/{workspace-manager → nemus}/references/suite-delete.md

@@ -16,6 +16,3 @@ Delete a saved suite.
 
 3. Confirm deletion.
 
-## Success Criteria
-
-- Suite is removed and no longer appears in `nemus suite list`.

package/skills/{workspace-manager → nemus}/references/suite-export.md

@@ -13,7 +13,3 @@ Export one or all suites to a JSON file for sharing.
 
 3. Share the exported file with teammates who can import it with `nemus suite import`.
 
-## Success Criteria
-
-- JSON file is created with suite data.
-- File can be imported with `nemus suite import`.

package/skills/{workspace-manager → nemus}/references/suite-import.md

@@ -13,7 +13,3 @@ Import suites from a JSON file (exported by `nemus suite export`).
 
 3. After import, verify with `nemus suite list`.
 
-## Success Criteria
-
-- Suites from the file are imported.
-- Imported suites appear in `nemus suite list`.

package/skills/{workspace-manager → nemus}/references/suite-use.md

@@ -21,7 +21,3 @@ Create a new workspace from a saved suite.
 
 4. After creation, suggest `nemus status <workspace>` to verify.
 
-## Success Criteria
-
-- Workspace is created with all suite repos cloned.
-- Post-clone hooks (if any) are executed.

package/skills/{workspace-manager → nemus}/references/switch-branch.md

@@ -19,7 +19,3 @@ If some repos fail to switch (due to uncommitted changes), suggest:
 - Committing or stashing changes first
 - Using `nemus status <name>` to check the state
 
-## Success Criteria
-
-- All repos without uncommitted changes are switched to the target branch.
-- Repos that failed to switch are clearly reported with the reason.

package/skills/{workspace-manager → nemus}/references/update-cache.md

@@ -17,6 +17,3 @@ Force refresh the GitHub repository cache so newly added repos become searchable
 
 3. Suggest using `nemus cache search <query>` or `nemus cache list` to browse the updated list.
 
-## Success Criteria
-
-- Cache is refreshed and the updated repo count is reported.

package/skills/{workspace-manager → nemus}/references/update-workspace.md

@@ -44,7 +44,3 @@ instance is tracked independently by `nemus status` and `nemus sync` and is labe
 > tracked repo — worktrees are invisible to `nemus status`/`nemus sync`. Use
 > `nemus update --repos <repo>:<suffix>` instead.
 
-## Success Criteria
-
-- All specified repos are cloned into the workspace.
-- User is informed of any repos skipped due to already existing.

package/skills/{workspace-manager → nemus}/references/workspace-cleanup.md

@@ -27,7 +27,3 @@ nemus cleanup <workspace> --git-clean --yes
 
 Remind the user they'll need to run `npm install` before building again.
 
-## Success Criteria
-
-- Selected directories are removed and disk space freed is reported.
-- User is reminded to re-run `npm install` before building.

package/skills/{workspace-manager → nemus}/references/workspace-diff.md

@@ -22,6 +22,3 @@ Show diff summary (staged/unstaged file counts, insertions, deletions) for all r
 
 4. If the user wants full diff content, they can pipe through `less` or redirect to a file.
 
-## Success Criteria
-
-- Per-repo diff summary is presented with file counts and line statistics.

package/skills/{workspace-manager → nemus}/references/workspace-doctor.md

@@ -21,7 +21,3 @@ Run comprehensive health checks on a workspace and return a health score (0-100)
    - `nemus cleanup` for disk space issues
    - `nemus branch create` or `nemus branch switch` for branch inconsistencies
 
-## Success Criteria
-
-- Health score and per-check results are clearly presented.
-- Actionable remediation steps are provided for any failures or warnings.

package/skills/{workspace-manager → nemus}/references/workspace-info.md

@@ -28,6 +28,3 @@ There is no dedicated `nemus info` CLI command. To get workspace information, co
 
 The MCP tool `workspace-info` provides detailed metadata programmatically.
 
-## Success Criteria
-
-- User gets the workspace information they need through the appropriate command.

package/skills/{workspace-manager → nemus}/references/workspace-status.md

@@ -10,7 +10,7 @@ nemus status <workspace>
 
 Alias:
 ```bash
-w st <workspace>
+nem st <workspace>
 ```
 
 Without a workspace name, prompts interactively:
@@ -29,15 +29,3 @@ Displays a table per repository showing:
 
 Plus a summary: clean repos, dirty repos, needs push, needs pull.
 
-## Suggested Follow-ups
-
-Based on the results:
-- Uncommitted changes → suggest `nemus diff <name>` to see details
-- Behind remote → suggest `nemus sync <name>` to pull latest
-- Mixed branches → suggest `nemus branch switch` to align
-- Repos ahead of remote → suggest pushing changes
-
-## Success Criteria
-
-- Per-repo status is displayed in a clear table.
-- Summary highlights any repos needing attention.

package/skills/{workspace-manager → nemus}/references/workspace-sync.md

@@ -20,7 +20,3 @@ Report results per repo:
 
 If some repos were skipped, suggest committing or stashing changes first, then re-run `nemus sync <name>`.
 
-## Success Criteria
-
-- All clean repos are pulled to latest.
-- User is informed of any skipped repos with uncommitted changes.

package/skills/refresh-workspace-docs.md

@@ -5,85 +5,13 @@ description: Refresh the per-repo documentation embedded in a workspace's contex
 
 # Refresh Workspace Docs
 
-When a workspace is created, each repo's own `AGENTS.md` / `CLAUDE.md` is
-embedded into the workspace-level context file (`AGENTS.md` / `.claude.md`)
-under the **Per-Repository Context** section. Those embedded copies are a
-snapshot taken at creation time — they do **not** auto-update when the repo
-later receives new commits that change its README or agent docs.
-
-This skill refreshes that embedded content so the agent works from the
-latest per-repo guidance.
-
-## When to Use
-
-- A workspace was created days/weeks ago and the repos have since changed.
-- A repo's `AGENTS.md` / `CLAUDE.md` / `README.md` was updated upstream and
-  you want the workspace context to reflect it.
-- The agent seems to be following outdated repo-specific instructions.
-- After a teammate merges changes to a repo's documentation.
-
-## Workflow
-
-Two steps: **sync the repos to latest**, then **regenerate the context**.
-
-### 1. Pull the latest for every repo in the workspace
-
-```bash
-nemus sync <workspace-name>
-```
-
-This `git pull`s every repo so their on-disk `README.md`, `AGENTS.md`, and
-`CLAUDE.md` reflect the latest upstream content. (Omit the name to sync the
-current workspace.)
-
-### 2. Regenerate the workspace context
-
-```bash
-w migrate
-```
-
-`nemus migrate` re-reads each repo's context files from disk and **surgically
-updates only the `## Per-Repository Context` section** of the workspace
-`AGENTS.md` / `.claude.md`. Your own notes (the `## Notes` section, saved
-`CONTEXT.md`, etc.) are preserved untouched.
-
-Preview what would change first with:
+Each repo's `AGENTS.md`/`CLAUDE.md` is embedded into the workspace context file's `## Per-Repository Context` section at creation time — a snapshot that does **not** auto-update. Refresh it in two steps:
 
 ```bash
-w migrate --dry-run
+nemus sync <workspace>       # 1. git pull every repo so on-disk docs are current
+nemus migrate                # 2. rebuild the Per-Repository Context section from disk
 ```
 
-## What Gets Refreshed
-
-The `## Per-Repository Context` section is rebuilt from each repo's context
-file, discovered in this priority order (per repo, up to 2 directory levels
-deep for monorepo packages):
-
-1. `AGENTS.md`
-2. `.claude.md`
-3. `CLAUDE.md`
-
-Each repo's content is embedded with imperative scoping ("You MUST follow
-these rules whenever you work with files inside `<repo>/`") and placed near
-the top of the workspace context file so the agent weights it heavily.
-
-## Notes
-
-- This only refreshes **embedded** per-repo docs in the workspace context
-  file. The repos themselves are updated by `nemus sync` in step 1.
-- `nemus migrate` runs across **all** workspaces. That's safe and idempotent —
-  every workspace gets its per-repo section refreshed from current on-disk
-  content. Use `--dry-run` first if you want to see scope.
-- If a workspace has no repo-level context files, the section is omitted
-  (or removed if it previously existed).
-
-## Example
-
-```bash
-# Workspace 'payments' was created 3 weeks ago; partnerships-api has since
-# rewritten its AGENTS.md with new Jira board instructions.
-
-nemus sync payments        # pull latest — partnerships-api/AGENTS.md now current
-w migrate --dry-run    # preview: "payments: would embed per-repo context from 4 location(s)"
-w migrate              # apply — workspace AGENTS.md now has the new instructions
-```
+- Use `nemus migrate --dry-run` first to preview scope.
+- `nemus migrate` runs across **all** workspaces; it's idempotent and only touches the `## Per-Repository Context` section — your `## Notes` and `CONTEXT.md` are preserved.
+- Per repo it embeds the first of `AGENTS.md` → `.claude.md` → `CLAUDE.md` found (up to 2 dir levels deep). If none exist, the section is omitted.