@astryxdesign/cli 0.7.2 → 0.7.3-canary.06872b4

package/clients/cli/commands/init.behavior.test.mjs

@@ -70,10 +70,12 @@ describe('astryx init — default (no flags)', () => {
 });
 
 describe('astryx init --features', () => {
-  it('--features agents writes AGENTS.md only', async () => {
+  it('--features agents writes AGENTS.md and the GEMINI.md import of it', async () => {
     const {status} = await runCli(['init', '--features', 'agents'], {cwd: tmpDir});
     expect(status).toBe(0);
     expect(exists('AGENTS.md')).toBe(true);
+    expect(read('GEMINI.md')).toBe(`${MARKER_START}\n@./AGENTS.md\n<!-- ASTRYX:END -->\n`);
+    expect(exists('theme.template.ts')).toBe(false);
   });
 
   it('--features theme writes the annotated theme template', async () => {
@@ -126,7 +128,234 @@ describe('astryx init --agent <preset>', () => {
   });
 });
 
+describe('astryx init from a subfolder', () => {
+  /** @param {string} dir */
+  const astryxProject = dir =>
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+
+  it('writes the agent docs at the project root and reports them from where it ran', async () => {
+    astryxProject(tmpDir);
+    const sub = path.join(tmpDir, 'src', 'app');
+    fs.mkdirSync(sub, {recursive: true});
+
+    const json = await runCli(['init', '--json'], {cwd: sub});
+    expect(json.status).toBe(0);
+    expect(JSON.parse(json.stdout).data.docsWritten).toEqual([
+      '../../AGENTS.md',
+      '../../GEMINI.md',
+    ]);
+    expect(read('AGENTS.md')).toContain(MARKER_START);
+    expect(fs.readdirSync(sub)).toEqual([]);
+  });
+
+  it('keeps --agent-docs-path relative to where it ran', async () => {
+    astryxProject(tmpDir);
+    const sub = path.join(tmpDir, 'docs');
+    fs.mkdirSync(sub);
+
+    const json = await runCli(['init', '--agent-docs-path', 'AI.md', '--json'], {cwd: sub});
+    expect(JSON.parse(json.stdout).data.docsWritten).toEqual(['AI.md']);
+    expect(fs.readFileSync(path.join(sub, 'AI.md'), 'utf8')).toContain(MARKER_START);
+    expect(exists('AGENTS.md')).toBe(false);
+  });
+});
+
+describe('astryx init in the home folder', () => {
+  const saved = {HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE};
+  const personal = '# My notes\n\nAlways use tabs.\n';
+
+  beforeEach(() => {
+    process.env.HOME = tmpDir;
+    process.env.USERPROFILE = tmpDir;
+    fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});
+    fs.writeFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), personal);
+  });
+  afterEach(() => {
+    for (const [key, value] of Object.entries(saved)) {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+  });
+
+  it('writes no agent docs, says why, and keeps the soft-failure exit code', async () => {
+    const json = await runCli(['init', '--json'], {cwd: tmpDir});
+    expect(json.status).toBe(0);
+    const env = JSON.parse(json.stdout);
+    expect(env.data.docsWritten).toEqual([]);
+    expect(env.data.docsError).toEqual({
+      kind: 'install-failed',
+      message: expect.stringMatching(/not written into the home folder/),
+    });
+
+    const text = await runCli(['init'], {cwd: tmpDir});
+    expect(text.status).toBe(0);
+    expect(text.stderr).toMatch(/not written into the home folder/);
+    expect(text.stderr).not.toMatch(/Error:/);
+
+    expect(read('.claude/CLAUDE.md')).toBe(personal);
+    expect(fs.readdirSync(tmpDir)).toEqual(['.claude']);
+  });
+
+  it('does not let a package.json in the home folder pull the docs there', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    const scratch = path.join(tmpDir, 'scratch');
+    fs.mkdirSync(scratch);
+
+    const json = await runCli(['init', '--json'], {cwd: scratch});
+    expect(json.status).toBe(0);
+    expect(JSON.parse(json.stdout).data.docsWritten).toEqual(['AGENTS.md', 'GEMINI.md']);
+    expect(fs.existsSync(path.join(scratch, 'AGENTS.md'))).toBe(true);
+    expect(exists('AGENTS.md')).toBe(false);
+    expect(read('.claude/CLAUDE.md')).toBe(personal);
+  });
+
+  it('--remove-agents in a folder in home never reaches the home folder', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, '.claude', 'CLAUDE.md'),
+      `${personal}\n<!-- ASTRYX:START -->\nAstryx v0.7.0\n<!-- ASTRYX:END -->\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    const scratch = path.join(tmpDir, 'scratch');
+    fs.mkdirSync(scratch);
+
+    const json = await runCli(['init', '--remove-agents', '--json'], {cwd: scratch});
+    expect(JSON.parse(json.stdout).data.removed).toBe(false);
+    expect(read('.claude/CLAUDE.md')).toContain('<!-- ASTRYX:START -->');
+
+    // Run in the home folder itself, it still removes the block there.
+    const home = await runCli(['init', '--remove-agents', '--json'], {cwd: tmpDir});
+    expect(JSON.parse(home.stdout).data.removed).toBe(true);
+    expect(read('.claude/CLAUDE.md')).toBe(personal);
+  });
+
+  it.each(['.gemini', '.claude'])('refuses the settings folder ~/%s', async folder => {
+    const dir = path.join(tmpDir, folder);
+    fs.mkdirSync(dir, {recursive: true});
+    const before = fs.readdirSync(dir);
+
+    const json = await runCli(['init', '--json'], {cwd: dir});
+    expect(json.status).toBe(0);
+    const env = JSON.parse(json.stdout);
+    expect(env.data.docsWritten).toEqual([]);
+    expect(env.data.docsError.message).toMatch(/settings folder in it outside a project/);
+    expect(fs.readdirSync(dir)).toEqual(before);
+    expect(read('.claude/CLAUDE.md')).toBe(personal);
+  });
+});
+
+describe('astryx init in an agent worktree inside a home settings folder', () => {
+  const saved = {HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE};
+
+  beforeEach(() => {
+    process.env.HOME = tmpDir;
+    process.env.USERPROFILE = tmpDir;
+  });
+  afterEach(() => {
+    for (const [key, value] of Object.entries(saved)) {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+  });
+
+  it.each([
+    ['Codex', path.join('.codex', 'worktrees', 'a1b2c3', 'web')],
+    ['Cursor', path.join('.cursor', 'worktrees', 'web', 'x9y8')],
+  ])('writes at the project root of a %s worktree', async (_tool, rel) => {
+    const project = path.join(tmpDir, rel);
+    fs.mkdirSync(path.join(project, 'src'), {recursive: true});
+    fs.writeFileSync(path.join(project, '.git'), 'gitdir: /elsewhere/.git/worktrees/web\n');
+    fs.writeFileSync(
+      path.join(project, 'package.json'),
+      JSON.stringify({name: 'web', dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+
+    const json = await runCli(['init', '--json'], {cwd: path.join(project, 'src')});
+    expect(json.status).toBe(0);
+    const env = JSON.parse(json.stdout);
+    expect(env.data.docsWritten).toEqual(['../AGENTS.md', '../GEMINI.md']);
+    expect(env.data.docsError).toBeNull();
+
+    const explicit = await runCli(['init', '--agent-docs-path', 'AI.md', '--json'], {
+      cwd: path.join(project, 'src'),
+    });
+    expect(JSON.parse(explicit.stdout).data.docsWritten).toEqual(['AI.md']);
+
+    // Nothing reaches the settings folder itself.
+    const settings = path.join(tmpDir, rel.split(path.sep)[0]);
+    expect(fs.readdirSync(settings)).toEqual(['worktrees']);
+  });
+});
+
+describe('astryx init and the project root', () => {
+  it('writes where it runs when no folder above has a package.json, as before', async () => {
+    const notes = path.join(tmpDir, 'notes');
+    fs.mkdirSync(notes);
+
+    const json = await runCli(['init', '--json'], {cwd: notes});
+    expect(json.status).toBe(0);
+    const env = JSON.parse(json.stdout);
+    expect(env.data.docsWritten).toEqual(['AGENTS.md', 'GEMINI.md']);
+    expect(env.data.docsError).toBeNull();
+    expect(fs.readdirSync(notes).sort()).toEqual(['AGENTS.md', 'GEMINI.md']);
+    expect(fs.readdirSync(tmpDir)).toEqual(['notes']);
+  });
+
+  it('writes at the project root that declares Astryx, past a nested package that does not', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    const functions = path.join(tmpDir, 'functions');
+    fs.mkdirSync(path.join(functions, 'src'), {recursive: true});
+    fs.writeFileSync(path.join(functions, 'package.json'), '{"name":"functions"}\n');
+
+    const json = await runCli(['init', '--json'], {cwd: path.join(functions, 'src')});
+    expect(JSON.parse(json.stdout).data.docsWritten).toEqual([
+      '../../AGENTS.md',
+      '../../GEMINI.md',
+    ]);
+    expect(fs.readdirSync(functions).sort()).toEqual(['package.json', 'src']);
+  });
+});
+
 describe('astryx init --remove-agents', () => {
+  it('run in a subfolder, removes what init wrote at the project root, with the same JSON shape', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    const sub = path.join(tmpDir, 'src', 'app');
+    fs.mkdirSync(sub, {recursive: true});
+    await runCli(['init'], {cwd: sub});
+    expect(exists('AGENTS.md')).toBe(true);
+
+    const text = await runCli(['init', '--remove-agents'], {cwd: sub});
+    expect(text.status).toBe(0);
+    expect(text.stdout).toMatch(/Removed empty \.\.\/\.\.\/AGENTS\.md/);
+    expect(exists('AGENTS.md')).toBe(false);
+    expect(exists('GEMINI.md')).toBe(false);
+
+    await runCli(['init'], {cwd: sub});
+    const json = await runCli(['init', '--remove-agents', '--json'], {cwd: sub});
+    expect(json.status).toBe(0);
+    // meta.answeredBy names the release that answered (spec AST-081).
+    expect(JSON.parse(json.stdout)).toEqual({
+      apiVersion: 1,
+      type: 'init.remove',
+      data: {removed: true},
+      meta: {answeredBy: expect.any(Object)},
+    });
+  });
+
   it('removes the Astryx section it previously installed', async () => {
     await runCli(['init', '--features', 'agents'], {cwd: tmpDir});
     expect(exists('AGENTS.md')).toBe(true);

package/clients/cli/commands/init.doc.mjs

@@ -16,10 +16,24 @@ export const doc = {
   summary: 'Initialize the design system in your project',
   description:
     'Non-interactive project setup (no prompts, so it behaves the same for humans, ' +
-    'agents, and CI). By default it installs the AGENTS.md/CLAUDE.md agent-docs, ' +
-    'including guidance from configured integrations, and prints getting-started ' +
-    "steps. --features and --all print only the chosen features' guidance (no " +
-    'getting-started steps); the theme feature also writes an annotated theme template. ' +
+    'agents, and CI). By default it writes the agent-docs block, including guidance ' +
+    'from configured integrations, to AGENTS.md and to the Claude Code file the project ' +
+    'has (CLAUDE.md, else .claude/CLAUDE.md; when CLAUDE.md exists, a block in ' +
+    '.claude/CLAUDE.md is removed, unless the project ignores CLAUDE.md, in which case a .claude/CLAUDE.md the ' +
+    'project commits keeps a copy), and a one-line import of AGENTS.md to GEMINI.md ' +
+    'unless GEMINI.md already imports it. It then prints getting-started steps. Agent ' +
+    'docs go to the project root: the nearest folder at or above this one whose ' +
+    'package.json declares an @astryxdesign package, else the nearest with any ' +
+    'package.json, else this folder. The search stops at a repository root and never ' +
+    'counts the home folder. In the home folder, or in a settings folder in it ' +
+    'such as ~/.gemini outside a project, no agent docs are written. Every folder of the ' +
+    'home folder whose name starts with a dot is a settings folder, and such a folder ' +
+    'itself never counts as a project, even with a package.json; a project inside one, ' +
+    'such as an agent worktree with its own package.json, works. The managed block is ' +
+    'written whatever ignore rules or generated markers say; the text around it is never changed. ' +
+    '--features and --all print only ' +
+    "the chosen features' " +
+    'guidance (no getting-started steps); the theme feature also writes an annotated theme template. ' +
     'Outside a project it writes the same files but prints no step that sets up a project: ' +
     'no getting-started steps, and no step that adds a theme to an app. ' +
         '--user writes the computer-level agent text instead (see the flag), in any folder, and touches nothing in the folder. ' +
@@ -44,8 +58,10 @@ export const doc = {
       flag: '--remove-agents',
       param: 'options.removeAgents',
       description:
-        'Remove the managed block from AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, .cursorrules, .hermes.md and HERMES.md ' +
-        "(deleting AGENTS.md or .claude/CLAUDE.md when only init's heading is left) and do nothing else. " +
+        'Remove the managed block from AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, GEMINI.md, .cursorrules, .hermes.md and HERMES.md, ' +
+        'at the project root (where init writes them) and in this folder ' +
+        "(deleting AGENTS.md or .claude/CLAUDE.md when only init's heading is left, and GEMINI.md when nothing is left) and do nothing else. " +
+        'Below the project root, a project-root agent file whose block resolves outside the project is left as it is, with a note. ' +
         '--features, --all, --agent and --agent-docs-path are refused; a file written with --agent-docs-path keeps its block',
     },
     {
@@ -66,7 +82,9 @@ export const doc = {
       choices: ['claude', 'cursor', 'codex', 'hermes', 'muse', 'all'],
       description:
         'Target AI tool for agent docs: claude (CLAUDE.md or .claude/CLAUDE.md, else creates .claude/CLAUDE.md), cursor (.cursorrules if present, else AGENTS.md), ' +
-        'codex and muse (AGENTS.md), hermes (.hermes.md or HERMES.md if present, else AGENTS.md), all (every existing agent doc, else AGENTS.md and .claude/CLAUDE.md). ' +
+        'codex and muse (AGENTS.md), hermes (.hermes.md or HERMES.md if present, else AGENTS.md), all (every existing agent doc except GEMINI.md, which keeps its ' +
+        'one-line import of AGENTS.md, else AGENTS.md and .claude/CLAUDE.md). With claude and all, when CLAUDE.md gets the block, .claude/CLAUDE.md gets none and ' +
+        'a block already there is removed, unless the project ignores CLAUDE.md: then a .claude/CLAUDE.md the project commits gets a copy too, with claude and all alike. ' +
         'An unknown tool exits 1 with ERR_UNKNOWN_AGENT. ' +
                 'Used only when agent docs are installed (the default, --all, or --features agents); --agent-docs-path takes precedence.',
     },
@@ -76,6 +94,7 @@ export const doc = {
       description:
         'Explicit file path(s) for agent docs, inside the project; takes precedence over --agent. ' +
         'If any path is outside the project, no agent docs are written and the command exits 1. ' +
+        'A path in the home folder itself, or in a settings folder in it outside a project (such as ~/.claude or ~/.claude/hooks), is refused with a note (exit 0), and nothing is written. ' +
         'Used only when agent docs are installed',
     },
   ],
@@ -90,11 +109,11 @@ export const doc = {
   exitCodes: [
     {
       code: 0,
-      when: 'success, including agent docs that could not be written for a reason other than a path escape (reported as docsError)',
+      when: "success, including agent docs left unwritten in five soft cases, each reported as docsError with one note: running in the home folder, or in a settings folder in it outside a project; a GEMINI.md that resolves outside the project; when init runs below the project root, a project-root agent file that resolves outside the project; the project's Claude Code file (root CLAUDE.md, or .claude/CLAUDE.md when there is no root one) when it resolves outside the project and is a block-less import of an existing AGENTS.md, which 0.7.1 left alone; and a .claude/CLAUDE.md that resolves outside the project and that 0.7.1 did not write: beside a CLAUDE.md the project ignores, the one --agent claude adds or a block-less import of an existing AGENTS.md; with --agent claude beside a CLAUDE.md, one whose block it would remove",
     },
     {
       code: 1,
-            when: 'an unknown --agent (ERR_UNKNOWN_AGENT) or feature, an --agent-docs-path outside the project, --remove-agents combined with install options, --user combined with --features, --all, --agent or --agent-docs-path, or --all with --features (ERR_INVALID_ARGUMENT)',
+      when: 'an unknown --agent (ERR_UNKNOWN_AGENT) or feature, an --agent-docs-path outside the project, --remove-agents combined with install options, --user combined with --features, --all, --agent or --agent-docs-path, or --all with --features (ERR_INVALID_ARGUMENT); or, when init runs at the project root, an agent file 0.7.1 also wrote there that resolves outside the project (ERR_PATH_TRAVERSAL, docsError path-safety, nothing written)',
     },
   ],
   related: ['doctor', 'upgrade', 'build', 'theme'],

package/clients/cli/commands/init.flag-help.test.mjs

@@ -67,6 +67,7 @@ describe('astryx init flag interactions', () => {
       expect(help).toContain(file);
     }
     expect(help).toMatch(/--agent-docs-path are refused/);
+    expect(help).toMatch(/at the project root \(where init writes them\) and in this folder/);
 
     await initJson(['--agent-docs-path', 'docs/AI.md']);
     await initJson([]);

package/clients/cli/commands/init.mjs

@@ -3,8 +3,8 @@
 /**
  * @file init command — thin wrapper around the init API.
  *
- * `astryx init` is non-interactive by default: it installs the AGENTS.md/
- * CLAUDE.md cheat sheet with NO prompts, so it behaves identically for humans,
+ * `astryx init` is non-interactive by default: it installs the agent-docs
+ * cheat sheet with NO prompts, so it behaves identically for humans,
  * AI agents, CI, and piped I/O — it never hangs or errors on a missing TTY.
  * Non-interactive feature install: `astryx init --features agents,theme,template`
  * Re-runnable: safe to run multiple times, idempotent.

package/clients/cli/commands/outside-project.test.mjs

@@ -541,7 +541,8 @@ describe('init outside a project (own)', () => {
       const dir = tmpDir('init');
       const json = await answer(['--json', 'init'], dir);
       expect(json.status).toBe(0);
-      expect(json.written).toEqual(['AGENTS.md']);
+      // GEMINI.md gets its one-line import of AGENTS.md (spec cli-surface INV31).
+      expect(json.written).toEqual(['AGENTS.md', 'GEMINI.md']);
       expect(json.envelope.data.nextSteps).toBe(false);
       const text = await runCli(['init'], tmpDir('init-text'));
       expect(text.stdout).not.toContain('Next steps');

package/clients/cli/commands/setup-nudge.test.mjs

@@ -121,6 +121,25 @@ describe('enforcement layer 3 — per-command setup nudge', () => {
     expect(r.stderr).toMatch(NUDGE);
   });
 
+  it.each([
+    ['in the home folder', ''],
+    ['at the top of a settings folder in it', '.dotfiles'],
+  ])('stays quiet %s, where init writes no agent docs', async (_label, rel) => {
+    const saved = {HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE};
+    process.env.HOME = tmp;
+    process.env.USERPROFILE = tmp;
+    try {
+      write(path.join(rel, 'package.json'), '{"name":"t"}');
+      const r = await runCli(['docs', 'tokens'], path.join(tmp, rel));
+      expect(r.stderr).not.toMatch(NUDGE);
+    } finally {
+      for (const [key, value] of Object.entries(saved)) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+    }
+  });
+
   it("in a project with only Core of another release, names adding the CLI at Core's version first, as the daily hint does", async () => {
     write(
       'package.json',
@@ -167,6 +186,48 @@ describe('enforcement layer 3 — per-command setup nudge', () => {
     expect((await runCli(['docs', 'tokens'], tmp)).stderr).not.toMatch(NUDGE);
   });
 
+  it('is quiet in a nested package once init has written the docs at the project root', async () => {
+    // init run in functions/ writes at the root that declares Astryx.
+    write('package.json', JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}));
+    write('AGENTS.md', MARKER);
+    write('functions/package.json', '{"name":"functions"}');
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'functions'));
+    expect(r.stderr).not.toMatch(NUDGE);
+  });
+
+  it('nudges in a nested package while the project root has no docs', async () => {
+    write('package.json', JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}));
+    write('functions/package.json', '{"name":"functions"}');
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'functions'));
+    expect(r.stderr).toMatch(NUDGE);
+  });
+
+  // Inside a git repository the project-root check above adds nothing to the
+  // walk up to the repository root: the same outcomes as without it.
+  it('inside a repository, is quiet in a nested package once init has written the docs at the project root', async () => {
+    fs.mkdirSync(path.join(tmp, '.git'));
+    write('package.json', JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}));
+    write('AGENTS.md', MARKER);
+    write('functions/package.json', '{"name":"functions"}');
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'functions'));
+    expect(r.stderr).not.toMatch(NUDGE);
+  });
+
+  it('inside a repository, still nudges when the only docs lie above the repository root', async () => {
+    write('package.json', JSON.stringify({name: 'outer', dependencies: {'@astryxdesign/core': '0.7.0'}}));
+    write('AGENTS.md', MARKER);
+    fs.mkdirSync(path.join(tmp, 'repo', '.git'), {recursive: true});
+    write('repo/package.json', '{"name":"repo"}');
+    // It declares Astryx: a folder that declares nothing is outside a
+    // project, where no reminder prints (spec AST-081 FR3).
+    write(
+      'repo/functions/package.json',
+      JSON.stringify({name: 'functions', dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'repo', 'functions'));
+    expect(r.stderr).toMatch(NUDGE);
+  });
+
   it('does not nudge for the installer command itself', async () => {
     asProject();
     expect((await runCli(['init'], tmp)).stderr).not.toMatch(NUDGE);

package/clients/cli/commands/upgrade.doc.mjs

@@ -21,6 +21,7 @@ export const doc = {
     'agent-docs block when Core or configured integration guidance changes. ' +
     'Dry-run by default. --apply writes codemod and receipt changes, runs hooks, then refreshes agent docs. ' +
     'Anything a post-codemod hook prints goes to stderr, so stdout carries only the result. ' +
+    'Run from a folder inside a project, it upgrades that project and names files in the result relative to the folder you ran it in. ' +
     'ShadCN-copied compositions are checked automatically during a normal upgrade, or alone with --registry. ' +
     'Outside a project, --list lists the codemods this release ships and --registry finds no copied compositions to update; ' +
     'a migration writes nothing and fails with ERR_VERSION_DETECT, because no installed Core names its target.',
@@ -69,8 +70,9 @@ export const doc = {
     {
       flag: '--path <dir>',
       param: 'options.path',
-      description: 'Source directory to scan',
-      default: './src',
+      description:
+        "Source directory to scan, relative to where you run the command, however you spell it. Without --path, the project's src folder, from any folder in the project",
+      default: './src at the project root',
     },
     {
       flag: '--install-deps',

package/clients/cli/commands/upgrade.mjs

@@ -31,8 +31,9 @@ export function registerUpgrade(program) {
     action:
       /**
        * @param {import('../../../api/upgrade/upgrade.mjs').UpgradeOptions} options
+       * @param {import('commander').Command} command
        */
-      async options => {
+      async (options, command) => {
         const json = program.opts().json || false;
         const isList = Boolean(options.list);
         // Silence the logger for --list so the handler renders from the
@@ -42,8 +43,14 @@ export function registerUpgrade(program) {
 
         /** @type {import('../../../api/upgrade/upgrade.type.mjs').UpgradeListResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeRegistryResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeStatusResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeRunResponse} */
         let result;
+        // `--path` shows its default in help, but a path nobody typed is the
+        // project's src, not one read from this folder: leave it unset.
+        const apiOptions =
+          command.getOptionValueSource('path') === 'default'
+            ? {...options, path: undefined}
+            : options;
         try {
-          result = await upgradeApi(options, {cwd: process.cwd()});
+          result = await upgradeApi(apiOptions, {cwd: process.cwd()});
         } catch (e) {
           // Re-enable the logger so the error is visible in text mode.
           // For --list the logger was silent; for other modes the API

package/clients/cli/commands/upgrade.subfolder-path.test.mjs

@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx upgrade` from a folder inside a project: a `--path` you type
+ * is read from that folder, however you spell it, and without `--path` the
+ * upgrade scans the project's own src. The option's default must not read as
+ * a typed `./src`. The `--json` result names files relative to the folder the
+ * command ran in.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+/** Core 0.7.0 renamed this prop; its codemod renames it on Typeahead. */
+const OLD_PROP_SOURCE =
+  "import {Typeahead} from '@astryxdesign/core';\n" +
+  'export const App = () => <Typeahead label="Fruit" emptySearchResultsText="None" />;\n';
+
+let root;
+
+/** @param {string} rel @param {string} body */
+function write(rel, body) {
+  const file = path.join(root, rel);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, body);
+}
+
+/** @param {string} rel */
+const renamed = rel =>
+  fs
+    .readFileSync(path.join(root, rel), 'utf-8')
+    .includes('emptySearchText="None"');
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-upgrade-subfolder-'));
+  write(
+    'package.json',
+    JSON.stringify({
+      name: 'app',
+      private: true,
+      dependencies: {'@astryxdesign/core': '0.7.0'},
+    }),
+  );
+  write(
+    'node_modules/@astryxdesign/core/package.json',
+    JSON.stringify({name: '@astryxdesign/core', version: '0.7.0'}),
+  );
+  write('src/App.tsx', OLD_PROP_SOURCE);
+  // A folder inside the project with source of its own and no package.json.
+  write('frontend/src/App.tsx', OLD_PROP_SOURCE);
+});
+
+afterEach(() => {
+  fs.rmSync(root, {recursive: true, force: true});
+});
+
+/** @param {string[]} args @param {string} [folder] */
+async function upgradeFrom(args, folder = 'frontend') {
+  const r = await runCli(
+    ['upgrade', '--from', '0.6.8', ...args, '--apply', '--json'],
+    {
+      cwd: path.join(root, folder),
+    },
+  );
+  expect(r.status).toBe(0);
+  return JSON.parse(r.stdout);
+}
+
+describe('upgrade --path from a folder inside the project', () => {
+  it.each([['./src'], ['src'], ['src/'], ['./src/']])(
+    'reads --path %s from the folder you ran in',
+    async spelling => {
+      const result = await upgradeFrom(['--path', spelling]);
+
+      expect(result.data.modifiedFiles).toEqual(['src/App.tsx']);
+      expect(renamed('frontend/src/App.tsx')).toBe(true);
+      expect(renamed('src/App.tsx')).toBe(false);
+    },
+  );
+
+  it("scans the project's src without --path", async () => {
+    const result = await upgradeFrom([]);
+
+    expect(result.data.modifiedFiles).toEqual(['../src/App.tsx']);
+    expect(renamed('src/App.tsx')).toBe(true);
+    expect(renamed('frontend/src/App.tsx')).toBe(false);
+  });
+
+  it('names files from the project root when run there', async () => {
+    const result = await upgradeFrom([], '.');
+
+    expect(result.data.modifiedFiles).toEqual(['src/App.tsx']);
+  });
+});

package/clients/cli/index.mjs

@@ -32,7 +32,12 @@ import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {installJsonShim} from './lib/json-shim.mjs';
 import {addDocHelp, markReportsResult} from './lib/define-command.mjs';
 import {doc as manifestDoc} from './commands/manifest.doc.mjs';
-import {isAstryxInitialized, isAstryxPromptInReach} from '../../foundation/agent-docs/agent-docs.mjs';
+import {
+  agentDocsTargetDir,
+  assertAgentDocsTarget,
+  isAstryxInitialized,
+  isAstryxPromptInReach,
+} from '../../foundation/agent-docs/agent-docs.mjs';
 import {CLI_ROOT} from '../../foundation/fs/paths.mjs';
 import {setupNudge} from '../../foundation/agent-docs/agent-doc-state.mjs';
 import * as debug from '../../foundation/debug/index.mjs';
@@ -635,6 +640,19 @@ export async function createProgram() {
       if (INTEGRATION_MANIFEST_FILES.some(file => fs.existsSync(path.join(cwd, file)))) return;
       if (inOwnSourceCheckout(cwd)) return; // developing Astryx itself, not an app
       if (isAstryxPromptInReach(cwd)) return; // already set up — stay quiet
+      // Where init writes the docs, by init's own rule: the project root, which
+      // can sit above a nested package such as functions/. Inside a git
+      // repository the walk above already reaches it (the root never lies
+      // above the repository root), so this changes nothing there; outside a
+      // repository the walk checks only cwd, and this finds the root.
+      if (isAstryxInitialized(agentDocsTargetDir(cwd))) return;
+      // In the home folder, or at the top of a settings folder in it, init
+      // writes no agent docs, so naming it would repeat on every command.
+      try {
+        assertAgentDocsTarget(agentDocsTargetDir(cwd));
+      } catch {
+        return;
+      }
       // Same wording as the core/cli postinstall nudges. getCliInvocation()
       // renders the correct form for THIS project — an integration's cliCommand,
       // scoped `npx @astryxdesign/cli` one-off, or `<pm> astryx` when installed —