refactor(hosts): defineHost() factory — 10 copy-paste host files become declarations

hosts/*.ts were ten copies of one file: runtimeRoot byte-identical in 9/10,
pathRewrites mechanically derivable from the host name for 7/10, the 11-entry
toolRewrites map byte-identical between openclaw and gbrain, and every asset
change a 10-file edit (cursor and slate had already fallen out of three other
hand-maintained lists). defineHost() owns the defaults; each host file now
declares only what makes it different (slate/cursor: 8 lines each). Shared
constants: CROSS_MODEL_RESOLVERS, GBRAIN_RESOLVERS, EXEC_STYLE_TOOL_REWRITES.
Genuinely-different things stayed explicit: codex/factory $GSTACK_ROOT
rewrites, hermes's tool vocabulary, claude's denylist+prefixable install,
opencode's wider runtimeRoot.

Proof: JSON.stringify(ALL_HOST_CONFIGS) dump-diff before/after EMPTY (and a
runtime walk confirmed no function-valued or undefined-keyed fields, so the
JSON diff is complete); gen:skill-docs --host all zero-diff; host-config +
gen-skill-docs + idempotency suites 485/485. Host files 595 -> 285 lines.
docs/ADDING_A_HOST.md teaches the factory pattern.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/ADDING_A_HOST.md

@@ -1,14 +1,16 @@
 # Adding a New Host to gstack
 
 gstack uses a declarative host config system. Each supported AI coding agent
-(Claude, Codex, Factory, Kiro, OpenCode, Slate, Cursor, OpenClaw) is defined
-as a typed TypeScript config object. Adding a new host means creating one file
-and re-exporting it. Zero code changes to the generator, setup, or tooling.
+(Claude, Codex, Factory, Kiro, OpenCode, Slate, Cursor, OpenClaw, Hermes,
+GBrain) is defined as a typed TypeScript config object built by the
+`defineHost()` factory. Adding a new host means creating one file and
+re-exporting it. Zero code changes to the generator, setup, or tooling.
 
 ## How it works
 
 ```
 hosts/
+├── define-host.ts   # defineHost() factory: shared defaults + derived fields
 ├── claude.ts        # Primary host
 ├── codex.ts         # OpenAI Codex CLI
 ├── factory.ts       # Factory Droid
@@ -16,11 +18,14 @@ hosts/
 ├── opencode.ts      # OpenCode
 ├── slate.ts         # Slate (Random Labs)
 ├── cursor.ts        # Cursor
-├── openclaw.ts      # OpenClaw (hybrid: config + adapter)
+├── openclaw.ts      # OpenClaw
+├── hermes.ts        # Hermes (Nous Research)
+├── gbrain.ts        # GBrain
 └── index.ts         # Registry: imports all, derives Host type
 ```
 
-Each config file exports a `HostConfig` object that tells the generator:
+Each config file calls `defineHost()` and exports the resulting `HostConfig`
+object, which tells the generator:
 - Where to put generated skills (paths)
 - How to transform frontmatter (allowlist/denylist fields)
 - What Claude-specific references to rewrite (paths, tool names)
@@ -35,59 +40,60 @@ copy, and tests all read from these configs. None of them have per-host code.
 
 ### 1. Create the config file
 
-Copy an existing config as a starting point. `hosts/opencode.ts` is a good
-minimal example. `hosts/factory.ts` shows tool rewrites and conditional fields.
-`hosts/openclaw.ts` shows the adapter pattern for hosts with different tool models.
-
-Create `hosts/myhost.ts`:
+Configs are built with the `defineHost()` factory in `hosts/define-host.ts`.
+You only write the fields that differ from the common external-host defaults;
+everything else is derived from the host name. A fully-default host is two
+fields (see `hosts/slate.ts` or `hosts/cursor.ts`):
 
 ```typescript
-import type { HostConfig } from '../scripts/host-config';
+import { defineHost } from './define-host';
 
-const myhost: HostConfig = {
+const myhost = defineHost({
   name: 'myhost',
   displayName: 'MyHost',
-  cliCommand: 'myhost',        // binary name for `command -v` detection
-  cliAliases: [],              // alternative binary names
-
-  globalRoot: '.myhost/skills/gstack',
-  localSkillRoot: '.myhost/skills/gstack',
-  hostSubdir: '.myhost',
-  usesEnvVars: true,           // false only for Claude (uses literal ~ paths)
-
-  frontmatter: {
-    mode: 'allowlist',         // 'allowlist' keeps only listed fields
-    keepFields: ['name', 'description'],
-    descriptionLimit: null,    // set to 1024 for hosts with limits
-  },
-
-  generation: {
-    generateMetadata: false,   // true only for Codex (openai.yaml)
-    skipSkills: ['codex'],     // codex skill is Claude-only
-  },
-
-  pathRewrites: [
-    { from: '~/.claude/skills/gstack', to: '~/.myhost/skills/gstack' },
-    { from: '.claude/skills/gstack', to: '.myhost/skills/gstack' },
-    { from: '.claude/skills', to: '.myhost/skills' },
-  ],
-
-  runtimeRoot: {
-    globalSymlinks: ['bin', 'browse/dist', 'browse/bin', 'gstack-upgrade', 'ETHOS.md'],
-    globalFiles: { 'review': ['checklist.md', 'TODOS-format.md'] },
-  },
-
-  install: {
-    prefixable: false,
-    linkingStrategy: 'symlink-generated',
-  },
-
-  learningsMode: 'basic',
-};
+});
 
 export default myhost;
 ```
 
+That expands to the full `HostConfig` with these defaults:
+
+- `cliCommand: 'myhost'` (the name; binary for `command -v` detection)
+- `cliAliases: []`
+- `globalRoot` / `localSkillRoot`: `.myhost/skills/gstack`, `hostSubdir`: `.myhost`
+- `usesEnvVars: true` (false only for Claude, which uses literal `~` paths)
+- `frontmatter`: allowlist keeping `name` + `description`, no description limit
+- `generation`: no metadata sidecar, `skipSkills: ['codex']` (codex skill is Claude-only)
+- `pathRewrites`: the standard trio derived from the resolved paths
+  (`~/.claude/skills/gstack` → `~/{globalRoot}`, `.claude/skills/gstack` →
+  `{localSkillRoot}`, `.claude/skills` → `{hostSubdir}/skills`)
+- `suppressedResolvers`: the GBrain pair (`GBRAIN_CONTEXT_LOAD`, `GBRAIN_SAVE_RESULTS`)
+- `runtimeRoot`: the shared asset list (`bin`, `browse/dist`, `browse/bin`,
+  `gstack-upgrade`, `ETHOS.md` + review checklist files)
+- `install`: `{ prefixable: false, linkingStrategy: 'symlink-generated' }`
+- `learningsMode: 'basic'`
+
+Override any field by passing it to `defineHost()`. Two path-rewrite options:
+
+- `extraPathRewrites`: appends entries AFTER the derived trio (e.g. kiro's
+  codex-path cleanup, or `{ from: 'CLAUDE.md', to: 'AGENTS.md' }` for
+  AGENTS.md hosts). Use this when the standard trio is right but you need more.
+- `pathRewrites`: replaces the derived list entirely. Only for non-mechanical
+  cases — codex and factory rewrite the global path to `$GSTACK_ROOT` and add
+  an extra review-path rewrite; claude has an empty list.
+
+The two are mutually exclusive (the factory throws if you pass both).
+
+Shared constants exported from `define-host.ts` for spread-composition:
+`CROSS_MODEL_RESOLVERS` (the five Codex-invoking resolvers suppressed on
+hosts that can't invoke other models), `GBRAIN_RESOLVERS` (the default
+suppression pair), and `EXEC_STYLE_TOOL_REWRITES` (the OpenClaw-style
+lowercase-tool rewrites shared by openclaw and gbrain).
+
+Good examples: `hosts/opencode.ts` (path + runtimeRoot overrides),
+`hosts/factory.ts` (tool rewrites and conditional fields), `hosts/hermes.ts`
+(AGENTS.md host with custom tool rewrites and resolver composition).
+
 ### 2. Register in the index
 
 Edit `hosts/index.ts`:
@@ -97,11 +103,11 @@ import myhost from './myhost';
 
 // Add to ALL_HOST_CONFIGS array:
 export const ALL_HOST_CONFIGS: HostConfig[] = [
-  claude, codex, factory, kiro, opencode, slate, cursor, openclaw, myhost
+  claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, myhost
 ];
 
 // Add to re-exports:
-export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, myhost };
+export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain, myhost };
 ```
 
 ### 3. Add to .gitignore
@@ -155,7 +161,8 @@ Key fields:
 | `frontmatter.descriptionLimitBehavior` | `error` (fail build), `truncate`, `warn` |
 | `frontmatter.conditionalFields` | Add fields based on template values (e.g., sensitive → disable-model-invocation) |
 | `frontmatter.renameFields` | Rename template fields (e.g., voice-triggers → triggers) |
-| `pathRewrites` | Literal replaceAll on content. Order matters. |
+| `pathRewrites` | Literal replaceAll on content. Order matters. Replaces the derived trio. |
+| `extraPathRewrites` | (defineHost input only) Appended after the derived trio. |
 | `toolRewrites` | Rewrite Claude tool names (e.g., "use the Bash tool" → "run this command") |
 | `suppressedResolvers` | Resolver functions that return empty for this host |
 | `coAuthorTrailer` | Git co-author string for commits |
@@ -165,8 +172,9 @@ Key fields:
 ## Adapter pattern (for hosts with different tool models)
 
 If string-replace tool rewrites aren't enough (the host has fundamentally
-different tool semantics), use the adapter pattern. See `hosts/openclaw.ts`
-and `scripts/host-adapters/openclaw-adapter.ts`.
+different tool semantics), use the adapter pattern: set the `adapter` field
+to the adapter module path. See `scripts/host-adapters/openclaw-adapter.ts`
+for the reference implementation (no shipped host currently sets `adapter`).
 
 The adapter runs as a post-processing step after all generic rewrites. It
 exports `transform(content: string, config: HostConfig): string`.