@technomoron/agent-run 0.99.27 → 0.99.29

package/CHANGES

@@ -1,6 +1,28 @@
 CHANGES
 =======
 
+Version 0.99.29 (2026-09-04)
+----------------------------
+* Add tracked per-profile project memory under `notes/memory`, while keeping
+  native Codex memories in ignored machine-local runtime state.
+* Detect older memory layouts before profile updates and agent launches, ask
+  before staging tracked moves with `git mv`, and support
+  `migrate-config --yes` for non-interactive migrations.
+* Make copied systemd updater files portable, install the helper under
+  `/usr/local/libexec`, and remove stale AI tool launchers before global
+  package updates.
+* Explain the shared configuration model for native coding agents in the
+  README.
+
+Version 0.99.28 (2026-08-30)
+----------------------------
+* Add interactive `agent-run setup [org/repo]`, make `agent-run generate` the
+  profile-initialization command, and retain `init` as a deprecated alias.
+* Use `~/.agent-run` as the single default config directory, overridable with
+  `--configdir`, `AGENT_CONFIG_DIR`, or a project-local `.agent-run.env`.
+* Resolve profiles from `package.json.repository` and avoid rewriting unchanged
+  generated files.
+
 Version 0.99.27 (2026-08-11)
 ----------------------------
 * Rename the unattended-run option from `--danger` to `--yolo` for Codex and

package/README.md

@@ -1,10 +1,46 @@
 # agent-run
 
-Small wrapper for AI coding CLIs like Codex and Claude.
+**Config once. Run with any native coding agent.**
 
-It keeps agent files out of normal repos and stores them in a separate
-agent config tree. By default, that tree lives beside owner/repo checkouts
-under the same code root.
+`agent-run` lets you manage Codex, Claude Code, Gemini CLI, and Grok Build from
+one shared configuration system while continuing to use each vendor's native
+agent.
+
+Keep agent configuration in a separate Git repository instead of adding
+agent-specific files to every codebase. Define project instructions, skills,
+MCP servers, policies, and reusable configuration fragments once, then generate
+the native configuration each agent expects.
+
+Configuration is template-based using Nunjucks/Jinja-style templates, making it
+easy to build hierarchical setups from global defaults, organization rules,
+project-specific settings, reusable fragments, and local overrides.
+
+`agent-run` generates isolated agent runtimes outside the source repository, so
+application repositories remain clean and developers do not have to maintain
+separate `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, skills, and tool configuration
+for every agent.
+
+The core idea is simple:
+
+**One configuration repository. One set of skills. Multiple native agents.**
+
+```text
+shared config repository
+        ↓
+global + project + local templates
+        ↓
+canonical instructions / skills / MCP
+        ↓
+agent-specific generated runtime
+        ↓
+Codex | Claude Code | Gemini CLI | Grok Build
+```
+
+The native agents remain native. `agent-run` does not replace their execution
+engines, authentication, models, or tooling. It provides the portable
+configuration layer around them.
+
+**Config once, run anywhere.**
 
 ## Model
 
@@ -17,31 +53,33 @@ There are three things:
 Example:
 
 ```text
-~/source/
-  agent-config/
-    agent-run.defaults.jsonc
-    org/
-      my-api/
-        agent-run.jsonc
-        local.md.njk       # optional
-        overrides/         # optional
-        live/
-          CLAUDE.md
-          .claude/
-          bin/
-          memories/
-            codex-home/
-              AGENTS.md
-              config.toml
-              skills/
+~/.agent-run/
+  agent-run.defaults.jsonc
   org/
     my-api/
+      agent-run.jsonc
+      local.md.njk       # optional
+      overrides/         # optional
+      notes/
+        memory/
+          README.md      # durable project memory, normally tracked
+      live/
+        CLAUDE.md
+        .claude/
+        bin/
+        memories/
+          codex-home/
+            AGENTS.md
+            config.toml
+            memories/    # native Codex memory, local generated state
+            skills/
+~/source/org/my-api/
 ```
 
 If your source repo is `~/source/org/my-api`, `agent-run` maps it to:
 
 ```text
-~/source/agent-config/org/my-api
+~/.agent-run/org/my-api
 ```
 
 The source repo stays clean. The agent files live in the matching path under
@@ -53,6 +91,7 @@ the agent config tree.
 - `agent-run.jsonc`: sparse profile manifest and profile-discovery marker
 - `local.md.njk`: optional project-specific instructions
 - `overrides/`: optional per-profile template overrides
+- `notes/memory/`: durable project memory shared through the config repository
 - `live/memories/codex-home/AGENTS.md`: generated Codex instructions
 - `live/memories/codex-home/config.toml`: generated Codex config
 - `live/memories/codex-home/skills/`: generated Codex skills
@@ -96,13 +135,15 @@ The mapped path is:
 
 1. `AGENT_RUN_PROFILE` in `.agent-run.env`
 2. GitHub `origin` remote
-3. `package.json.name`
-4. the project path as `[parent]/[current]`
+3. `package.json.repository` (string or object `url`)
+4. `package.json.name`
+5. the project path as `[parent]/[current]`
 
 Examples:
 
 - `AGENT_RUN_PROFILE=org/my-api` -> `org/my-api`
 - `AGENT_RUN_PROFILE=unrelated/hello` -> `unrelated/hello`
+- `package.json.repository = "github:org/my-api"` -> `org/my-api`
 - `package.json.name = "@org/my-api"` -> `org/my-api`
 - `package.json.name = "my-api"` -> `my-api`
 - `/work/org/my-api` with none of the above -> `org/my-api`
@@ -124,20 +165,10 @@ AGENT_RUN_PROFILE=org/my-api
 
 Config root:
 
-- default for a project at `[code]/owner/repo`: `[code]/agent-config`
-- override with `--config-root /path/to/agent-configs`
+- default: `~/.agent-run`
+- override with `--configdir=/path/to/agent-configs`
 - override with `AGENT_CONFIG_DIR=/path/to/agent-configs`
-- override with `AGENT_CONFIG_ROOT=/path/to/agent-configs`
-- or set `AGENT_CONFIG_DIR=/path/to/agent-configs` or `AGENT_CONFIG_ROOT=/path/to/agent-configs` in `.agent-run.env`
-
-For commands without a project root, `agent-run` looks for an existing config
-root in these locations:
-
-- Windows: `~/Documents/code/agent-config`, `~/Documents/code/agent-configs`,
-  `~/Desktop/code/agent-config`, `~/Desktop/code/agent-configs`,
-  `C:\code\agent-config`, `C:\code\agent-configs`
-- Unix: `~/code/agent-config`, `~/code/agent-configs`, `~/agent-config`,
-  `~/agent-configs`, `~/.agent-config`, `~/.agent-configs`
+- or set `AGENT_CONFIG_DIR=/path/to/agent-configs` in `.agent-run.env`
 
 ## Commands
 
@@ -163,6 +194,26 @@ When `~/.codex/auth.json` exists, profile-specific Codex homes link their
 `auth.json` to that shared login cache so changing profiles does not require a
 new ChatGPT login.
 
+### Project Memory
+
+Each profile has a durable `notes/memory/` directory outside the source repo.
+`README.md` is a short index; agents read only the linked files relevant to the
+current task. Agents may update project memory only when the user explicitly
+asks them to remember or update something for that project.
+
+Codex's native `$CODEX_HOME/memories/` remains under ignored `live/` state. It
+is generated, machine-local recall data and is not copied into the tracked
+project memory directory. Project memory is plain Markdown so it can be
+reviewed and shared through the Git repository that normally holds the
+`.agent-run` config tree.
+
+When a profile still uses `memory/`, loose `memory*.md` files, or Markdown files
+directly under the old `memories/` directory, agent-run detects the old layout
+before updating or launching an agent. If those files are tracked, agent-run
+shows the moves and asks before staging them with `git mv`. In a non-Git config
+tree, or for untracked files, it uses ordinary filesystem moves. Non-interactive
+runs stop with a command that can confirm the migration explicitly.
+
 Claude Code currently has no `--cd` equivalent. `agent-run` keeps Claude's
 process cwd at the project root, appends the generated `CLAUDE.md` with
 `--append-system-prompt-file`, passes generated settings with `--settings`, and
@@ -186,12 +237,12 @@ to warn and continue for a specific invocation.
 Initialize mapped files for the current repo:
 
 ```sh
-agent-run init
+agent-run generate
 ```
 
 This creates `<config-root>/agent-run.defaults.jsonc` when needed and a minimal
 `agent-run.jsonc` marker for the mapped profile. It does not create empty local
-instruction or override files.
+instruction or override files. `agent-run init` remains as a deprecated alias.
 
 Edit the source file for the current repo:
 
@@ -209,19 +260,18 @@ agent-run update
 ```
 
 `update` requires an existing profile marker or local/legacy instruction file;
-it does not silently scaffold an unconfigured project. Use `agent-run init` or
+it does not silently scaffold an unconfigured project. Use `agent-run generate` or
 the tool command's `--create` option first.
 
 Regenerate every profile under the config root without requiring matching code
 checkouts:
 
 ```sh
-agent-run update --all ~/.agent-config
+agent-run update --all ~/.agent-run
 ```
 
 If the config root argument is omitted, `update --all` uses the normal configured
-root. Without a project path, that falls back to `$HOME/.agent-config`; for
-project commands, the default is `[code]/agent-config`.
+root. Without an override, the root is `$HOME/.agent-run`.
 
 You can also generate from a tool command and stop before launch:
 
@@ -245,27 +295,28 @@ Per-profile override templates can be placed in:
 - `overrides/codex-config.toml.njk`
 - `overrides/claude-settings.json.njk`
 
-## Starter Config
+## Default Config Tree
 
-A complete starter lives in `examples/basic-config`. It includes a minimal
+A complete default tree lives in `examples/basic-config`. It includes a minimal
 project, `.agent-run.env`, root manifest defaults, global templates and
 snippets, profile-local templates, skill templates, a personal memory skill,
 profile skill overrides, tool config overrides, guardrails, checks, and
 generated runtime paths.
 
-To create the packaged starter agent files in your resolved config root:
+To install the default tree and detected profile in your resolved config root:
 
 ```sh
 agent-run setup
 ```
 
-Or choose a destination:
+Or select a profile non-interactively:
 
 ```sh
-agent-run setup ~/.agent-config
+agent-run setup myorg/myrepo
 ```
 
-The copy skips files that already exist, so local edits are preserved.
+Use `--configdir=DIR` to choose a different destination. The copy skips files
+that already exist, so local edits are preserved.
 
 Try it from a checkout:
 
@@ -298,14 +349,17 @@ agent-run check --all ~/source
 Migrate an existing config tree to the manifest/template layout:
 
 ```sh
-agent-run migrate-config ~/.agent-config
+agent-run migrate-config --yes ~/.agent-run
 ```
 
 This preserves `AGENTS-MODS.md`, creates `local.md.njk` and a sparse
 `agent-run.jsonc` marker for legacy profiles, creates the root defaults and
 `global/` templates, moves loose review files into `reviews/`, moves loose
-`memory*.md` files into `memories/`, and moves old Codex runtime files into
-`live/memories/codex-home` without overwriting existing files.
+project memory files into each profile's `notes/memory/`, and moves old Codex
+runtime files into `live/memories/codex-home` without overwriting existing
+files. Use `--yes` to confirm tracked `git mv` operations in a non-interactive
+run. Omit `--yes` to review and confirm tracked moves interactively. The
+command stages moves but never commits them.
 
 ## Systemd Jobs
 

package/dist/checks.js

@@ -8,6 +8,7 @@ exports.hasErrors = hasErrors;
 const fs = require("fs");
 const path = require("path");
 const constants_1 = require("./constants");
+const config_tree_1 = require("./config-tree");
 const manifest_1 = require("./manifest");
 const project_1 = require("./project");
 const renderer_1 = require("./renderer");
@@ -47,6 +48,9 @@ function checkAgentDirectory(projectRoot, agentDir) {
     if (!(0, manifest_1.isProfileConfigured)(agentDir)) {
         return [{ message: `missing manifest or legacy/local source file in ${agentDir}`, severity: 'ERROR' }];
     }
+    for (const legacyPath of (0, config_tree_1.describeLegacyProfileLayout)(agentDir)) {
+        findings.push({ message: `old profile layout needs migration: ${legacyPath}`, severity: 'ERROR' });
+    }
     for (const relativeTemplate of constants_1.REQUIRED_GLOBAL_TEMPLATES) {
         if (!fs.existsSync(path.join(configRoot, relativeTemplate))) {
             findings.push({

package/dist/cli.js

@@ -25,7 +25,7 @@ function applyGlobalOptions(options) {
 }
 function extractCommand(args) {
     if (args.length === 0) {
-        (0, utils_1.fail)('usage: agent-run <codex|claude|check|init|edit|update> [options] (run with --help for details)');
+        (0, utils_1.fail)('usage: agent-run <codex|claude|check|setup|generate|edit|update> [options] (run with --help for details)');
     }
     if (isHelpFlag(args[0])) {
         printHelp('general');
@@ -50,6 +50,8 @@ function parseCommand(command, args) {
             return parseCheckCommand(args);
         case 'init':
             return parseInitCommand(args);
+        case 'generate':
+            return parseGenerateCommand(args);
         case 'setup':
             return parseSetupCommand(args);
         case 'edit':
@@ -85,18 +87,18 @@ function extractGlobalOptions(argv) {
         else if (arg === '-v' || arg === '--verbose') {
             options.verbose = true;
         }
-        else if (arg === '--config-root') {
+        else if (arg === '--configdir') {
             const nextArg = argv[index + 1];
             if (nextArg === undefined) {
-                (0, utils_1.fail)('missing value for --config-root');
+                (0, utils_1.fail)('missing value for --configdir');
             }
             options.configRootOverride = path.resolve(nextArg);
             index += 1;
         }
-        else if (arg.startsWith('--config-root=')) {
-            const rootValue = arg.slice('--config-root='.length);
+        else if (arg.startsWith('--configdir=')) {
+            const rootValue = arg.slice('--configdir='.length);
             if (!rootValue) {
-                (0, utils_1.fail)('missing value for --config-root');
+                (0, utils_1.fail)('missing value for --configdir');
             }
             options.configRootOverride = path.resolve(rootValue);
         }
@@ -196,8 +198,24 @@ function parseCheckCommand(inputArgs) {
 function parseInitCommand(inputArgs) {
     return { command: 'init', targetPath: parseSinglePath(inputArgs, 'init') };
 }
+function parseGenerateCommand(inputArgs) {
+    return { command: 'generate', targetPath: parseSinglePath(inputArgs, 'generate') };
+}
 function parseSetupCommand(inputArgs) {
-    return { command: 'setup', targetPath: parseSinglePath(inputArgs, 'setup', (0, project_1.defaultConfigRoot)()) };
+    let profile = null;
+    for (const arg of inputArgs) {
+        if (isHelpFlag(arg)) {
+            printHelp('setup');
+        }
+        if (arg.startsWith('--')) {
+            (0, utils_1.fail)(`unknown setup option: ${arg}`);
+        }
+        if (profile !== null) {
+            (0, utils_1.fail)('setup accepts at most one profile argument');
+        }
+        profile = arg;
+    }
+    return { command: 'setup', profile };
 }
 function parseEditCommand(inputArgs) {
     return { command: 'edit', targetPath: parseSinglePath(inputArgs, 'edit') };
@@ -236,16 +254,22 @@ function parseUpdateCommand(inputArgs) {
 }
 function parseMigrateConfigCommand(inputArgs) {
     let configRoot = (0, project_1.defaultConfigRoot)();
+    let yes = false;
     for (const arg of inputArgs) {
         if (isHelpFlag(arg)) {
             printHelp('migrate-config');
         }
-        if (arg.startsWith('--')) {
+        if (arg === '--yes') {
+            yes = true;
+        }
+        else if (arg.startsWith('--')) {
             (0, utils_1.fail)(`unknown migrate-config option: ${arg}`);
         }
-        configRoot = arg;
+        else {
+            configRoot = arg;
+        }
     }
-    return { command: 'migrate-config', configRoot: path.resolve(configRoot) };
+    return { command: 'migrate-config', configRoot: path.resolve(configRoot), yes };
 }
 function isHelpFlag(value) {
     return value === '-h' || value === '--help';
@@ -274,8 +298,9 @@ function renderHelp(topic) {
             '  --all       Check every repo under path',
             ''
         ],
-        init: ['Usage:', '  agent-run init [path]', '', 'Create a minimal mapped profile marker and render generated files.', ''],
-        setup: ['Usage:', '  agent-run setup [config-root]', '', 'Create starter agent configuration files in the config root.', ''],
+        init: ['Usage:', '  agent-run init [path]', '', 'Deprecated alias for `agent-run generate [path]`.', ''],
+        generate: ['Usage:', '  agent-run generate [path]', '', 'Create a minimal mapped profile marker and render generated files.', ''],
+        setup: ['Usage:', '  agent-run setup [org/repo]', '', 'Install the default config tree and selected profile.', ''],
         edit: ['Usage:', '  agent-run edit [path]', '', 'Create or open the editable local profile template.', ''],
         update: [
             'Usage:',
@@ -287,9 +312,12 @@ function renderHelp(topic) {
         ],
         'migrate-config': [
             'Usage:',
-            '  agent-run migrate-config [config-root]',
+            '  agent-run migrate-config [--yes] [config-root]',
             '',
             'Convert an existing agent config tree to the current manifest and global-template layout.',
+            '',
+            'Options:',
+            '  --yes  Confirm tracked Git moves without prompting',
             ''
         ]
     };
@@ -300,25 +328,25 @@ function renderHelp(topic) {
         `agent-run ${agentRunVersion()}`,
         '',
         'Usage:',
-        '  agent-run <codex|claude|check|setup|init|edit|update> [options]',
+        '  agent-run <codex|claude|check|setup|generate|edit|update> [options]',
         '',
         'Commands:',
         '  codex [--none] [--create] [--local] [--show] [--generate] [--yolo|--sandboxed] [--network] [args...]',
         '                                           Run codex with generated private config',
         '  claude [--none] [--create] [--local] [--show] [--generate] [--yolo] [args...]',
         '                                           Run claude with generated private config',
-        '  setup [config-root]                    Create starter files in the agent-config root',
+        '  setup [org/repo]                      Install the default tree and selected profile',
         '  check [--all] [path]                  Validate generated profile output',
-        '  init [path]                           Create a sparse profile marker and render output',
+        '  generate [path]                       Create a sparse profile marker and render output',
         '  edit [path]                           Create or open local.md.njk',
         '  update [--all] [path]                 Regenerate existing profile output',
-        '  migrate-config [config-root]           Convert existing config tree layout',
+        '  migrate-config [--yes] [config-root]   Convert existing config tree layout',
         '',
         'Global options:',
         '  -h, --help         Show this help text',
         '  -V, --version      Show the agent-run version',
         '  -v, --verbose      Print path resolution and wrapper actions',
-        '  --config-root DIR  Override the agent-config root',
+        '  --configdir=DIR    Override the config directory',
         '',
         'Run wrapper options:',
         '  --local            Warn about local AI files instead of failing',
@@ -351,7 +379,7 @@ function normalizeCommandName(value) {
     if (base === 'agent-run') {
         return null;
     }
-    return ['codex', 'claude', 'check', 'setup', 'init', 'edit', 'update', 'migrate-config'].includes(base)
+    return ['codex', 'claude', 'check', 'setup', 'generate', 'init', 'edit', 'update', 'migrate-config'].includes(base)
         ? base
         : null;
 }