@guiho/mirror 3.1.0 → 3.1.2

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.1] - 2026-06-07
+
+### Changed
+
+- Changed Mirror skill installation paths to the standard `.agents/skills` and `~/.agents/skills` directories.
+- Changed automatic skill installation to global-only by default while keeping explicit local installation available through `mirror agents install local`.
+- Changed no-argument `mirror` startup to run configured agent setup before showing help.
+- Updated documentation, schema text, and tests to describe the standard agent skill directories.
+
 ## [3.1.0] - 2026-06-07
 
 ### Added

package/DOCS.md

@@ -194,12 +194,14 @@ mirror agents install global
 mirror agents instructions
 ```
 
-- `install local`: Writes `.opencode/skills/guiho-as-mirror/SKILL.md` in the project.
-- `install global`: Writes `~/.config/opencode/skills/guiho-as-mirror/SKILL.md`.
+- `install local`: Writes `.agents/skills/guiho-as-mirror/SKILL.md` in the project.
+- `install global`: Writes `~/.agents/skills/guiho-as-mirror/SKILL.md`.
 - `instructions`: Creates or updates `AGENTS.md` with the GUIHO Mirror semantic versioning section.
 
 Global skill installation uses the user home directory. Tests and automation can override that home root with `MIRROR_AGENT_HOME`.
 
+Automatic skill installation is global-only by default. Use `mirror agents install local` when a project-local `.agents/skills/guiho-as-mirror/SKILL.md` copy is intentionally needed.
+
 ### `mirror version`
 
 Reads, plans, and applies version changes.
@@ -304,24 +306,29 @@ Agent settings tell AI coding agents how to prepare release documentation and wh
 - `write_changelog`: Optional. Tell agents whether changelog edits are allowed. Default: `true`.
 - `changelog_path`: Optional. Changelog file path for agents. Default: `CHANGELOG.md`.
 - `auto_agents_md`: Optional. Insert Mirror guidance into `AGENTS.md` when present. Default: `true`.
-- `auto_skill_install`: Optional. Install `guiho-as-mirror` when missing. Default: `true`.
+- `auto_skill_install`: Optional. Install `guiho-as-mirror` globally when missing. Default: `true`.
 
 Set `write_changelog = false` when agents must skip changelog edits, even if a changelog exists. Set `changelog_path` when the changelog is not at the project root or when a package inside a monorepo writes release notes elsewhere.
 
+Mirror uses standard agent skill directories:
+
+- Local: `.agents/skills/<skill-name>/SKILL.md`
+- Global: `~/.agents/skills/<skill-name>/SKILL.md`
+
 ## Agent Automation
 
-Mirror can self-provision AI-agent instructions for projects that use opencode-compatible skills.
+Mirror can self-provision AI-agent instructions for projects that use standard agent skill directories.
 
-When automation is enabled, project commands check for `AGENTS.md` and for local/global `guiho-as-mirror` skill installation. If guidance is missing, Mirror notifies the user and writes the missing skill or AGENTS section.
+When automation is enabled, project commands check for `AGENTS.md` and for global `guiho-as-mirror` skill installation. If guidance is missing, Mirror notifies the user and writes the missing global skill or AGENTS section. Running `mirror` with no arguments performs this configured setup before showing help. Mirror does not automatically write a local skill file; local installation is explicit.
 
 Automation is controlled by `[agents]`.
 
 - Disable AGENTS.md insertion with `auto_agents_md = false`.
-- Disable local/global skill installation with `auto_skill_install = false`.
+- Disable automatic global skill installation with `auto_skill_install = false`.
 - Disable changelog edits by agents with `write_changelog = false`.
 - Direct agents to the correct changelog with `changelog_path = "path/to/CHANGELOG.md"`.
 
-The generated AGENTS section instructs agents to invoke `guiho-as-mirror` for versioning work, inspect `mirror.config.toml`, respect `write_changelog`, and use `changelog_path` for changelog edits.
+The generated AGENTS section instructs agents to invoke `guiho-as-mirror` for versioning work, inspect `mirror.config.toml`, respect `write_changelog`, and use `changelog_path` for changelog edits. Use `mirror agents install local` only when a project-local skill copy is desired explicitly.
 
 ## Release Safety Rules
 

package/README.md

@@ -86,8 +86,8 @@ Validates and inspects configuration.
 
 #### `mirror agents`
 Installs Mirror-aware agent guidance for projects that use AI coding agents.
-- `mirror agents install local`: Installs the bundled `guiho-as-mirror` skill at `.opencode/skills/guiho-as-mirror/SKILL.md`.
-- `mirror agents install global`: Installs the bundled `guiho-as-mirror` skill at `~/.config/opencode/skills/guiho-as-mirror/SKILL.md`.
+- `mirror agents install local`: Installs the bundled `guiho-as-mirror` skill at `.agents/skills/guiho-as-mirror/SKILL.md`.
+- `mirror agents install global`: Installs the bundled `guiho-as-mirror` skill at `~/.agents/skills/guiho-as-mirror/SKILL.md`.
 - `mirror agents instructions`: Creates or updates `AGENTS.md` with the GUIHO Mirror semantic versioning section.
 
 #### `mirror version`
@@ -132,14 +132,14 @@ allow_dirty = false                    # Optional. Allow dirty Git worktree. Def
 write_changelog = true                 # Optional. Tell agents changelog edits are allowed. Default: true.
 changelog_path = "CHANGELOG.md"         # Optional. Changelog file path for agents. Default: "CHANGELOG.md".
 auto_agents_md = true                  # Optional. Insert Mirror guidance into AGENTS.md when present. Default: true.
-auto_skill_install = true              # Optional. Install guiho-as-mirror when missing. Default: true.
+auto_skill_install = true              # Optional. Install guiho-as-mirror globally when missing. Default: true.
 ```
 
 ### Agent Automation
 
-Mirror is designed to be safely used by AI agents. Project commands automatically check for `AGENTS.md` and the `guiho-as-mirror` skill, then add the Mirror guidance or install the missing skill when automation is enabled.
+Mirror is designed to be safely used by AI agents. Project commands automatically check for `AGENTS.md` and the `guiho-as-mirror` skill, then add the Mirror guidance or install the missing skill when automation is enabled. Running `mirror` with no arguments also performs this configured agent setup before showing help.
 
-Set `write_changelog = false` when agents should skip changelog edits during release preparation. Set `changelog_path = "docs/CHANGELOG.md"` when the changelog is not at the project root. Set `auto_agents_md = false` or `auto_skill_install = false` to opt out of automatic guidance insertion or skill installation.
+Set `write_changelog = false` when agents should skip changelog edits during release preparation. Set `changelog_path = "docs/CHANGELOG.md"` when the changelog is not at the project root. Set `auto_agents_md = false` to opt out of automatic guidance insertion, or `auto_skill_install = false` to opt out of automatic global skill installation.
 
 ### Safety & Git Automation
 

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@guiho/mirror",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "exports": "./source/guiho-mirror.ts",
   "publish": {
     "include": [

package/library/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../source/agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EACV,2BAA2B,EAC3B,mBAAmB,EACnB,8BAA8B,EAC9B,gBAAgB,EAChB,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,YAAY,CAAA;AAInB,eAAO,MAAM,eAAe,oBAAoB,CAAA;AAChD,eAAO,MAAM,0BAA0B,mDAAmD,CAAA;AAE1F,eAAO,MAAM,0BAA0B,EAAE,mBAKxC,CAAA;AAED,eAAO,MAAM,mBAAmB,6jBAO/B,CAAA;AAED,KAAK,sBAAsB,GAAG;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,KAAK,yBAAyB,GAAG,sBAAsB,GAAG;IACxD,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,KAAK,4BAA4B,GAAG,gBAAgB,GAAG;IACrD,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,OAAO,uBAAuB,EAAE,UAAS,sBAA2B,WAI1G,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,OAAO,uBAAuB,EAAE,UAAS,sBAA2B,YACvD,CAAA;AAEpD,eAAO,MAAM,kBAAkB,GAC7B,OAAO,uBAAuB,EAC9B,UAAS,yBAA8B,KACtC,OAAO,CAAC,wBAAwB,CAelC,CAAA;AAED,eAAO,MAAM,8BAA8B,GAAU,KAAK,MAAM,EAAE,gBAAc,KAAG,OAAO,CAAC,8BAA8B,CAkBxH,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAWrD,CAAA;AAED,eAAO,MAAM,0BAA0B,GAAU,UAAS,gBAAqB,KAAG,OAAO,CAAC,mBAAmB,CAa5G,CAAA;AAED,eAAO,MAAM,wBAAwB,GACnC,UAAS,4BAAiC,EAC1C,SAAQ,CAAC,OAAO,EAAE,MAAM,KAAK,IAAe,KAC3C,OAAO,CAAC,2BAA2B,CAoBrC,CAAA"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../source/agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EACV,2BAA2B,EAC3B,mBAAmB,EACnB,8BAA8B,EAC9B,gBAAgB,EAChB,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,YAAY,CAAA;AAInB,eAAO,MAAM,eAAe,oBAAoB,CAAA;AAChD,eAAO,MAAM,0BAA0B,mDAAmD,CAAA;AAE1F,eAAO,MAAM,0BAA0B,EAAE,mBAKxC,CAAA;AAED,eAAO,MAAM,mBAAmB,6jBAO/B,CAAA;AAED,KAAK,sBAAsB,GAAG;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,KAAK,yBAAyB,GAAG,sBAAsB,GAAG;IACxD,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,KAAK,4BAA4B,GAAG,gBAAgB,GAAG;IACrD,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,OAAO,uBAAuB,EAAE,UAAS,sBAA2B,WAI1G,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,OAAO,uBAAuB,EAAE,UAAS,sBAA2B,YACvD,CAAA;AAEpD,eAAO,MAAM,kBAAkB,GAC7B,OAAO,uBAAuB,EAC9B,UAAS,yBAA8B,KACtC,OAAO,CAAC,wBAAwB,CAelC,CAAA;AAED,eAAO,MAAM,8BAA8B,GAAU,KAAK,MAAM,EAAE,gBAAc,KAAG,OAAO,CAAC,8BAA8B,CAkBxH,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAWrD,CAAA;AAED,eAAO,MAAM,0BAA0B,GAAU,UAAS,gBAAqB,KAAG,OAAO,CAAC,mBAAmB,CAa5G,CAAA;AAED,eAAO,MAAM,wBAAwB,GACnC,UAAS,4BAAiC,EAC1C,SAAQ,CAAC,OAAO,EAAE,MAAM,KAAK,IAAe,KAC3C,OAAO,CAAC,2BAA2B,CAkBrC,CAAA"}

package/library/agents.js

@@ -25,8 +25,8 @@ Use [agents].changelog_path as the changelog file path. If it is missing, use CH
 `;
 export const resolveMirrorSkillPath = (scope, options = {}) => {
     if (scope === 'local')
-        return resolve(options.cwd ?? process.cwd(), '.opencode', 'skills', mirrorSkillName, 'SKILL.md');
-    return resolve(resolveMirrorAgentHome(options.homeDirectory), '.config', 'opencode', 'skills', mirrorSkillName, 'SKILL.md');
+        return resolve(options.cwd ?? process.cwd(), '.agents', 'skills', mirrorSkillName, 'SKILL.md');
+    return resolve(resolveMirrorAgentHome(options.homeDirectory), '.agents', 'skills', mirrorSkillName, 'SKILL.md');
 };
 export const isMirrorSkillInstalled = (scope, options = {}) => existsSync(resolveMirrorSkillPath(scope, options));
 export const installMirrorSkill = async (scope, options = {}) => {
@@ -91,16 +91,11 @@ export const runMirrorAgentAutomation = async (options = {}, notify = () => { })
     if (settings.autoAgentsMd)
         result.agentsMd = await ensureMirrorAgentsInstructions(cwd, false);
     if (settings.autoSkillInstall) {
-        for (const scope of ['local', 'global']) {
-            if (isMirrorSkillInstalled(scope, { cwd, homeDirectory: options.homeDirectory }))
-                continue;
+        const scope = 'global';
+        if (!isMirrorSkillInstalled(scope, { cwd, homeDirectory: options.homeDirectory })) {
             const path = resolveMirrorSkillPath(scope, { cwd, homeDirectory: options.homeDirectory });
             notify(`notice: ${mirrorSkillName} skill not found ${scope}; Mirror is installing it at ${path}`);
-            const installed = await installMirrorSkill(scope, { cwd, homeDirectory: options.homeDirectory, overwrite: false });
-            if (scope === 'local')
-                result.localSkill = installed;
-            if (scope === 'global')
-                result.globalSkill = installed;
+            result.globalSkill = await installMirrorSkill(scope, { cwd, homeDirectory: options.homeDirectory, overwrite: false });
         }
     }
     return result;
@@ -183,7 +178,7 @@ const embeddedMirrorSkillContent = [
     '',
     'Common configuration keys: `[version].source`, `[version].output`, `[version].prerelease_id`, `[git].tag_template`, `[git].commit`, `[git].push`, `[git].allow_dirty`, `[agents].write_changelog`, `[agents].changelog_path`, `[agents].auto_agents_md`, and `[agents].auto_skill_install`.',
     '',
-    'Agent automation options default to true. Set `write_changelog = false` to tell agents to skip changelog edits, `changelog_path = "docs/CHANGELOG.md"` to specify the changelog file, `auto_agents_md = false` to stop Mirror from inserting its AGENTS.md section, and `auto_skill_install = false` to stop Mirror from installing `guiho-as-mirror` when missing.',
+    'Agent automation options default to true. Set `write_changelog = false` to tell agents to skip changelog edits, `changelog_path = "docs/CHANGELOG.md"` to specify the changelog file, `auto_agents_md = false` to stop Mirror from inserting its AGENTS.md section, and `auto_skill_install = false` to stop Mirror from installing `guiho-as-mirror` globally when missing.',
     '',
     '## CLI Reference',
     '',

package/library/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AA2DH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;EAc5B,CAAA;AAEJ,eAAO,MAAM,YAAY,GAAU,kBAA+B,kBAoEjE,CAAA"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AA2DH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;EAc5B,CAAA;AAEJ,eAAO,MAAM,YAAY,GAAU,kBAA+B,kBAwEjE,CAAA"}

package/library/cli.js

@@ -61,6 +61,9 @@ export const runMirrorCli = async (rawArgs = process.argv.slice(2)) => {
     try {
         if (effectiveArgs.includes('--no-color'))
             process.env['NO_COLOR'] = '1';
+        if (rawArgs.length === 0) {
+            await prepareAgents({});
+        }
         if (effectiveArgs.includes('--help')) {
             const parsed = parseMirrorCliOptions(effectiveArgs);
             const cwd = resolve(parsed.cwd ?? process.cwd());

package/library/reporter.js

@@ -73,7 +73,7 @@ export const reportConfigSchema = (format = 'text') => {
         '  write_changelog = true | false            Optional. Tell agents to write changelog entries. Default: true.',
         '  changelog_path = "<path>"                 Optional. Changelog file path for agents. Default: "CHANGELOG.md".',
         '  auto_agents_md = true | false             Optional. Insert Mirror guidance into AGENTS.md when present. Default: true.',
-        '  auto_skill_install = true | false         Optional. Install guiho-as-mirror when missing. Default: true.',
+        '  auto_skill_install = true | false         Optional. Install guiho-as-mirror globally when missing. Default: true.',
         '',
     ].join('\n');
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/mirror",
   "description": "Open source project versioning for Bun, npm, JSR, and Git.",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "type": "module",
   "main": "./library/guiho-mirror.js",
   "types": "./library/guiho-mirror.d.ts",

package/skills/guiho-as-mirror/SKILL.md

@@ -147,7 +147,7 @@ auto_skill_install = true
 
 Supported version sources and outputs are `package.json`, `jsr.json`, and `git`. Supported Git tag templates are `v{version}`, `{name}@{version}`, and `{name}/v{version}`.
 
-Agent automation options default to true. Set `write_changelog = false` to tell agents to skip changelog edits, `changelog_path = "docs/CHANGELOG.md"` to specify the changelog file, `auto_agents_md = false` to stop Mirror from inserting its AGENTS.md section, and `auto_skill_install = false` to stop Mirror from installing `guiho-as-mirror` when missing.
+Agent automation options default to true. Set `write_changelog = false` to tell agents to skip changelog edits, `changelog_path = "docs/CHANGELOG.md"` to specify the changelog file, `auto_agents_md = false` to stop Mirror from inserting its AGENTS.md section, and `auto_skill_install = false` to stop Mirror from installing `guiho-as-mirror` globally when missing.
 
 ## CLI Reference