Merge pull request #58 from sampleXbro/develop

Develop

Author: sampleXbro

.agents/skills/add-agent-target/SKILL.md

@@ -33,6 +33,7 @@ Use this skill when the task is to add a brand-new supported agent target to thi
 - Prefer official docs and other primary sources. Use vendor examples or source code only when official docs are incomplete, and call that out explicitly.
 - Separate the target product from the current assistant runtime before making format decisions. Do not confuse a generated target like `codex-cli` with Codex desktop/chat, or local CLI MCP config with app-managed connectors.
 - Capture the target's real capability map for every canonical feature: rules, additionalRules, commands, agents, skills, mcp, hooks, ignore, permissions.
+- Fill in the descriptor `metadata` block (`displayName`, `category`, `officialUrl`, `shortDescription`). This is required at compile time and drives every auto-generated tool list in README + website. The scaffold leaves `TODO(agentsmesh-scaffold)` markers — replace them with the values from your Phase 1 research before commit.
 - When a feature is `none` but `skills` is `native` or `embedded`, evaluate whether `supportsConversion` should project that feature as skills. If the target reads skill bundles, commands and agents with no native surface should be projected as skills via `supportsConversion: { commands: true, agents: true }` and registered in `src/config/core/conversions.ts` with `DEFAULT_*_TO_SKILLS`. Do not add lint warnings for features that are projected as skills — only warn for features that are truly dropped.
 - Start from `agentsmesh target scaffold <id>` when building a built-in target. Do not hand-write the 10 skeleton files the scaffold produces.
 - Write failing tests first for every new behavior. Do not implement first and backfill later.
@@ -41,7 +42,7 @@ Use this skill when the task is to add a brand-new supported agent target to thi
 - Cover all edge cases for the new target, including legacy paths, fallbacks, malformed files, partial support, and unsupported features.
 - Wire descriptor capabilities for both project and global scope. New targets must include global mode unless the target has no global config surface at all, and that absence must be documented.
 - Update every affected command surface and user-facing document so the new target is discoverable and accurately described.
-- Update the compatibility matrix to reflect native, embedded, partial, or unsupported features. The matrix auto-builds from descriptor capabilities; `pnpm matrix:verify` must pass.
+- Update the compatibility matrix to reflect native, embedded, partial, or unsupported features. The matrix auto-builds from descriptor capabilities; `pnpm matrix:verify` must pass. The same script auto-generates the import-targets table, homepage tool list, and README tool list from descriptor `metadata` — no manual edits to those tables.
 - Update init detection and import empty-state messaging for the new target when native files exist.
 - Reuse existing capability-focused tests where possible; extend them instead of duplicating assertions across multiple files.
 - Preserve the canonical `.agentsmesh/` contract. If the target cannot represent a feature natively, model that explicitly instead of inventing fake native output.

.agents/skills/add-agent-target/references/target-addition-checklist.md

@@ -6,7 +6,10 @@ Concrete audit list for adding a built-in agent target. For the step-by-step wor
 
 Every item must have a primary-source link before coding starts:
 
-- Official docs URL for the tool
+- Official docs URL for the tool (becomes `metadata.officialUrl` — must be a canonical, stable URL)
+- Human-readable display name (becomes `metadata.displayName` — used in every doc table and tool list)
+- One-line description (becomes `metadata.shortDescription` — used in tool lists for SEO)
+- Tool category — one of: `cli` | `ide` | `agent-platform` (becomes `metadata.category` — groups the target on the homepage and supported-tools page)
 - Exact product surface being implemented (CLI vs desktop vs chat — often different config systems)
 - Project-scope config directory and root-instruction file
 - Global-scope config directory and root-instruction file
@@ -51,10 +54,21 @@ Shared code to audit, not usually modify:
 
 ## Documentation Touchpoints
 
-- `README.md` — matrix tables update automatically via `pnpm matrix:generate`
-- `website/src/content/docs/reference/supported-tools.mdx` — single docs page for per-target detail (paths, native vs embedded, limitations). Update this manually.
+The following are **all auto-generated** by `pnpm matrix:generate` from descriptor data — no manual edits:
+
+- `README.md` — feature matrices + tool-list (from `metadata` + `capabilities`)
+- `website/src/content/docs/reference/supported-tools.mdx` — feature matrices (from `capabilities`)
+- `website/src/content/docs/cli/import.mdx` — import-targets table (from `metadata` + `descriptor.importer`)
+- `website/src/content/docs/index.mdx` — homepage tool-list (from `metadata` grouped by `category`)
+
+Manual edits:
+
+- `website/src/content/docs/reference/supported-tools.mdx` — per-target detail sections (paths, native vs embedded, limitations, global-mode notes). Add a section for the new target.
 - `docs/prd-v2-complete.md` — only if the architecture contract changes
-- No other docs pages should need edits per repo rules
+
+After adding the descriptor metadata, run `pnpm matrix:generate && pnpm matrix:verify`. CI will fail any PR where docs drift from `TARGET_REGISTRY` (see `src/targets/catalog/target-metadata-registry.ts`).
+
+No other docs pages should need edits per repo rules.
 
 ## Unit Tests
 
@@ -143,10 +157,12 @@ Before marking complete, every command must exit 0:
 
 - Did you search the internet first, using official docs only?
 - Did you start from `agentsmesh target scaffold <id>`, or did you hand-write the skeleton?
+- Did you replace every `TODO(agentsmesh-scaffold)` marker in the descriptor `metadata` block with real values (`displayName`, `category`, `officialUrl`, `shortDescription`)?
 - Did you write failing tests first?
 - Did you add rich fixtures instead of placeholders?
 - Did you register the id in all three catalog files (`target-ids.ts`, `builtin-targets.ts`, `import-maps/index.ts`)?
 - Did you include global mode, or document the decision to omit it?
 - Did you check conversion eligibility for `none` features — could commands/agents be projected as skills instead of dropped?
-- Did you update `supported-tools.mdx` with per-target detail?
-- Did every verification command pass?
+- Did you run `pnpm matrix:generate` to refresh README + website auto-generated blocks from the new descriptor `metadata`?
+- Did you update `supported-tools.mdx` with per-target detail (paths, native vs embedded, limitations, global-mode notes)?
+- Did every verification command pass, including `pnpm matrix:verify`?

.agentsmesh/.lock

@@ -1,7 +1,7 @@
 # Auto-generated. DO NOT EDIT MANUALLY.
 # Tracks the state of all config files for team conflict resolution.
 
-generated_at: 2026-05-09T14:39:23.798Z
+generated_at: 2026-05-11T09:59:03.607Z
 generated_by: serhii
 lib_version: 0.16.0
 checksums:
@@ -22,8 +22,8 @@ checksums:
   permissions.yaml: sha256:c806acb62daf533af836dc113be37e9840a2a9b3e21b984c5909fcfb16eb52f2
   rules/_root.md: sha256:5c0ad47e9507d3ffbf19d01acb7fe166b19f82dcad8f80cc49b43ced633a9ddc
   rules/typescript.md: sha256:18f52143dfdd3e219a5c6d6c0feb7283fe74cce99458c46dafcd1c3620ad4fba
-  skills/add-agent-target/SKILL.md: sha256:2aca4da8dad8e7dd6740dfae026408d64f9ec4f649980f1781b3414261c5b7b4
-  skills/add-agent-target/references/target-addition-checklist.md: sha256:f735648de63644832b106c1dd8a64e00976a8025325c532548751e97b0d8342a
+  skills/add-agent-target/SKILL.md: sha256:b425055659d29f74dbbe97966f6396e918d96cb0736d1448217656cf26b410f6
+  skills/add-agent-target/references/target-addition-checklist.md: sha256:c2f4db92fd672349496c541bc3813bd3ba26781dbf7d0a154449fc8ef2242dab
   skills/add-global-mode-target/SKILL.md: sha256:88347b6ff928213abaf37d110d252bc51c999a44f3463cbfb328cfb15609f3d5
   skills/add-global-mode-target/references/global-mode-target-checklist.md: sha256:61f8827978f90ee079e2dfd426ef25b17e77c71d9f79c5f81ebc700379f6fafc
   skills/changelog-generator/SKILL.md: sha256:0973622bc8b1e48f4de7eef712dfad42740fe8252f1632ef14a5a7f44d34a4d3

.agentsmesh/skills/add-agent-target/SKILL.md

@@ -33,6 +33,7 @@ Use this skill when the task is to add a brand-new supported agent target to thi
 - Prefer official docs and other primary sources. Use vendor examples or source code only when official docs are incomplete, and call that out explicitly.
 - Separate the target product from the current assistant runtime before making format decisions. Do not confuse a generated target like `codex-cli` with Codex desktop/chat, or local CLI MCP config with app-managed connectors.
 - Capture the target's real capability map for every canonical feature: rules, additionalRules, commands, agents, skills, mcp, hooks, ignore, permissions.
+- Fill in the descriptor `metadata` block (`displayName`, `category`, `officialUrl`, `shortDescription`). This is required at compile time and drives every auto-generated tool list in README + website. The scaffold leaves `TODO(agentsmesh-scaffold)` markers — replace them with the values from your Phase 1 research before commit.
 - When a feature is `none` but `skills` is `native` or `embedded`, evaluate whether `supportsConversion` should project that feature as skills. If the target reads skill bundles, commands and agents with no native surface should be projected as skills via `supportsConversion: { commands: true, agents: true }` and registered in `src/config/core/conversions.ts` with `DEFAULT_*_TO_SKILLS`. Do not add lint warnings for features that are projected as skills — only warn for features that are truly dropped.
 - Start from `agentsmesh target scaffold <id>` when building a built-in target. Do not hand-write the 10 skeleton files the scaffold produces.
 - Write failing tests first for every new behavior. Do not implement first and backfill later.
@@ -41,7 +42,7 @@ Use this skill when the task is to add a brand-new supported agent target to thi
 - Cover all edge cases for the new target, including legacy paths, fallbacks, malformed files, partial support, and unsupported features.
 - Wire descriptor capabilities for both project and global scope. New targets must include global mode unless the target has no global config surface at all, and that absence must be documented.
 - Update every affected command surface and user-facing document so the new target is discoverable and accurately described.
-- Update the compatibility matrix to reflect native, embedded, partial, or unsupported features. The matrix auto-builds from descriptor capabilities; `pnpm matrix:verify` must pass.
+- Update the compatibility matrix to reflect native, embedded, partial, or unsupported features. The matrix auto-builds from descriptor capabilities; `pnpm matrix:verify` must pass. The same script auto-generates the import-targets table, homepage tool list, and README tool list from descriptor `metadata` — no manual edits to those tables.
 - Update init detection and import empty-state messaging for the new target when native files exist.
 - Reuse existing capability-focused tests where possible; extend them instead of duplicating assertions across multiple files.
 - Preserve the canonical `.agentsmesh/` contract. If the target cannot represent a feature natively, model that explicitly instead of inventing fake native output.

.agentsmesh/skills/add-agent-target/references/target-addition-checklist.md

@@ -6,7 +6,10 @@ Concrete audit list for adding a built-in agent target. For the step-by-step wor
 
 Every item must have a primary-source link before coding starts:
 
-- Official docs URL for the tool
+- Official docs URL for the tool (becomes `metadata.officialUrl` — must be a canonical, stable URL)
+- Human-readable display name (becomes `metadata.displayName` — used in every doc table and tool list)
+- One-line description (becomes `metadata.shortDescription` — used in tool lists for SEO)
+- Tool category — one of: `cli` | `ide` | `agent-platform` (becomes `metadata.category` — groups the target on the homepage and supported-tools page)
 - Exact product surface being implemented (CLI vs desktop vs chat — often different config systems)
 - Project-scope config directory and root-instruction file
 - Global-scope config directory and root-instruction file
@@ -51,10 +54,21 @@ Shared code to audit, not usually modify:
 
 ## Documentation Touchpoints
 
-- `README.md` — matrix tables update automatically via `pnpm matrix:generate`
-- `website/src/content/docs/reference/supported-tools.mdx` — single docs page for per-target detail (paths, native vs embedded, limitations). Update this manually.
+The following are **all auto-generated** by `pnpm matrix:generate` from descriptor data — no manual edits:
+
+- `README.md` — feature matrices + tool-list (from `metadata` + `capabilities`)
+- `website/src/content/docs/reference/supported-tools.mdx` — feature matrices (from `capabilities`)
+- `website/src/content/docs/cli/import.mdx` — import-targets table (from `metadata` + `descriptor.importer`)
+- `website/src/content/docs/index.mdx` — homepage tool-list (from `metadata` grouped by `category`)
+
+Manual edits:
+
+- `website/src/content/docs/reference/supported-tools.mdx` — per-target detail sections (paths, native vs embedded, limitations, global-mode notes). Add a section for the new target.
 - `docs/prd-v2-complete.md` — only if the architecture contract changes
-- No other docs pages should need edits per repo rules
+
+After adding the descriptor metadata, run `pnpm matrix:generate && pnpm matrix:verify`. CI will fail any PR where docs drift from `TARGET_REGISTRY` (see `src/targets/catalog/target-metadata-registry.ts`).
+
+No other docs pages should need edits per repo rules.
 
 ## Unit Tests
 
@@ -143,10 +157,12 @@ Before marking complete, every command must exit 0:
 
 - Did you search the internet first, using official docs only?
 - Did you start from `agentsmesh target scaffold <id>`, or did you hand-write the skeleton?
+- Did you replace every `TODO(agentsmesh-scaffold)` marker in the descriptor `metadata` block with real values (`displayName`, `category`, `officialUrl`, `shortDescription`)?
 - Did you write failing tests first?
 - Did you add rich fixtures instead of placeholders?
 - Did you register the id in all three catalog files (`target-ids.ts`, `builtin-targets.ts`, `import-maps/index.ts`)?
 - Did you include global mode, or document the decision to omit it?
 - Did you check conversion eligibility for `none` features — could commands/agents be projected as skills instead of dropped?
-- Did you update `supported-tools.mdx` with per-target detail?
-- Did every verification command pass?
+- Did you run `pnpm matrix:generate` to refresh README + website auto-generated blocks from the new descriptor `metadata`?
+- Did you update `supported-tools.mdx` with per-target detail (paths, native vs embedded, limitations, global-mode notes)?
+- Did every verification command pass, including `pnpm matrix:verify`?

.aider/skills/add-agent-target/SKILL.md

@@ -33,6 +33,7 @@ Use this skill when the task is to add a brand-new supported agent target to thi
 - Prefer official docs and other primary sources. Use vendor examples or source code only when official docs are incomplete, and call that out explicitly.
 - Separate the target product from the current assistant runtime before making format decisions. Do not confuse a generated target like `codex-cli` with Codex desktop/chat, or local CLI MCP config with app-managed connectors.
 - Capture the target's real capability map for every canonical feature: rules, additionalRules, commands, agents, skills, mcp, hooks, ignore, permissions.
+- Fill in the descriptor `metadata` block (`displayName`, `category`, `officialUrl`, `shortDescription`). This is required at compile time and drives every auto-generated tool list in README + website. The scaffold leaves `TODO(agentsmesh-scaffold)` markers — replace them with the values from your Phase 1 research before commit.
 - When a feature is `none` but `skills` is `native` or `embedded`, evaluate whether `supportsConversion` should project that feature as skills. If the target reads skill bundles, commands and agents with no native surface should be projected as skills via `supportsConversion: { commands: true, agents: true }` and registered in `src/config/core/conversions.ts` with `DEFAULT_*_TO_SKILLS`. Do not add lint warnings for features that are projected as skills — only warn for features that are truly dropped.
 - Start from `agentsmesh target scaffold <id>` when building a built-in target. Do not hand-write the 10 skeleton files the scaffold produces.
 - Write failing tests first for every new behavior. Do not implement first and backfill later.
@@ -41,7 +42,7 @@ Use this skill when the task is to add a brand-new supported agent target to thi
 - Cover all edge cases for the new target, including legacy paths, fallbacks, malformed files, partial support, and unsupported features.
 - Wire descriptor capabilities for both project and global scope. New targets must include global mode unless the target has no global config surface at all, and that absence must be documented.
 - Update every affected command surface and user-facing document so the new target is discoverable and accurately described.
-- Update the compatibility matrix to reflect native, embedded, partial, or unsupported features. The matrix auto-builds from descriptor capabilities; `pnpm matrix:verify` must pass.
+- Update the compatibility matrix to reflect native, embedded, partial, or unsupported features. The matrix auto-builds from descriptor capabilities; `pnpm matrix:verify` must pass. The same script auto-generates the import-targets table, homepage tool list, and README tool list from descriptor `metadata` — no manual edits to those tables.
 - Update init detection and import empty-state messaging for the new target when native files exist.
 - Reuse existing capability-focused tests where possible; extend them instead of duplicating assertions across multiple files.
 - Preserve the canonical `.agentsmesh/` contract. If the target cannot represent a feature natively, model that explicitly instead of inventing fake native output.