docs: simplify fork onboarding with pond-agent.json identity template

README.md

@@ -31,11 +31,14 @@ Tip: you can also ask follow-ups by commenting on the same issue.
 If you want your own pond node (your own repo + your own agent):
 
 1) **Fork** this repo
-2) In your fork:
+2) In your fork: edit `pond-agent.json` → replace placeholder values → commit
+3) In your fork:
    - enable **Issues**
    - enable **Actions workflows**
-3) Add **one** model key (example: `GEMINI_API_KEY`)
-4) Ask your question in **Issues**
+4) Add **one** model key (example: `GEMINI_API_KEY`)
+5) Ask your question in **Issues**
+
+Your Cave Scribe will respond automatically.
 
 Fork guide + setup:
 - `docs/SETUP.md`

docs/FORK_GUIDE.md

@@ -12,6 +12,33 @@ You ask questions via GitHub Issues. A GitHub Action replies as the Cave Scribe
 - Fork: `MirrorAgent1/lore-keeper`
 - Optional private canon repo (recommended): your own `lore-scrolls`
 
+## Activate Your Cave Scribe
+
+Forks automatically include a small identity file:
+- `pond-agent.json`
+
+To activate your node identity (no coding):
+
+1) Fork the repository
+2) Open `pond-agent.json`
+3) Click **✏️ Edit**
+4) Replace the placeholder values, for example:
+
+```json
+{
+  "agent_id": "22915",
+  "agent_name": "Tommy's Cave Scribe",
+  "builder": "tommyn9",
+  "repo": "tommyn9-22915/lore-keeper",
+  "role": "Lore Keeper",
+  "pond_enabled": true
+}
+```
+
+5) Commit the change
+
+Once committed, your agent identity is active.
+
 ## 1) Enable Actions
 
 In your fork:

docs/POND_AGENT_SPEC_v0.1.md

@@ -10,6 +10,8 @@ Status: **draft** / evolving.
 
 ## 1) File: `pond-agent.json`
 
+This repo uses a **minimal identity file** at the root for fork UX.
+
 Schema (optional):
 - `docs/pond-agent.schema.json`
 
@@ -19,13 +21,14 @@ Each Pond Agent repo should include a root-level:
 
 This file is intended to be human-editable and safe to publish.
 
-### 1.1 Required fields
+### 1.1 Required fields (minimal identity)
 
-- `spec_version` (string) — currently `"0.1"`
-- `id` (string) — stable identifier (recommend reverse-dns or owner.repo)
-- `name` (string)
-- `role` (string)
+- `agent_id` (string) — set to a unique value (any scheme is fine)
+- `agent_name` (string)
+- `builder` (string) — GitHub username
 - `repo` (string) — `owner/repo`
+- `role` (string)
+- `pond_enabled` (boolean)
 
 ### 1.2 Recommended fields
 
@@ -39,6 +42,9 @@ This file is intended to be human-editable and safe to publish.
 
 See: [`/pond-agent.json`](../pond-agent.json)
 
+Advanced example (optional):
+- `docs/pond-agent.example.advanced.json`
+
 Validate locally:
 - `npm run validate:pond-agent`
 

docs/SETUP.md

@@ -19,6 +19,18 @@ You ask questions via **GitHub Issues**. A GitHub Action runs the Cave Scribe an
 
 > If you see a workflow page that says **“Disabled”** (for example: **Rebuild Scroll Index**), it usually means Actions haven’t been enabled yet on that fork, or the workflow was disabled in the Actions UI.
 
+## Register Your Pond Identity (no coding)
+
+Every Cave Scribe node has a small identity file:
+- `pond-agent.json`
+
+After forking:
+- edit `pond-agent.json`
+- replace the placeholder fields
+- commit the change
+
+This allows the Mirror pond to discover your agent in the future.
+
 ## 2) Add at least one model provider key
 
 The Cave Scribe supports multiple providers to survive free-tier rate limits.

docs/pond-agent.example.advanced.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://toadaid.github.io/schemas/pond-agent/v0.1.json",
+  "spec_version": "0.1",
+  "id": "mirroragent1.lore-keeper",
+  "name": "Lore Keeper",
+  "role": "Agent1 / Cave Scribe",
+  "repo": "MirrorAgent1/lore-keeper",
+  "homepage": "https://github.com/MirrorAgent1/lore-keeper",
+  "interfaces": {
+    "github_issues": {
+      "enabled": true,
+      "url": "https://github.com/MirrorAgent1/lore-keeper/issues"
+    },
+    "telegram": {
+      "enabled": false,
+      "chat_id": null
+    }
+  },
+  "summon": {
+    "agent1": ["@MirrorAgent1", "@agent1", "awaken"],
+    "agent0": ["@toadaid-agent0", "@agent0", "keeper"]
+  },
+  "lore": {
+    "local_paths": ["lore/"],
+    "index_path": "data/scroll_index.json",
+    "primary_scroll": "lore/toadgod-lore.json"
+  },
+  "bridge": {
+    "pond_agents_config": "data/pond_agents.json",
+    "dispatch_secret_preferred": "POND_DISPATCH_TOKEN",
+    "dispatch_secret_legacy": "AGENT0_DISPATCH_TOKEN"
+  },
+  "notes": "Advanced example (optional). The recommended fork UX is the minimal root pond-agent.json." 
+}

docs/pond-agent.schema.json

@@ -1,59 +1,16 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://toadaid.github.io/schemas/pond-agent/v0.1.schema.json",
-  "title": "Pond Agent Spec v0.1",
+  "$id": "https://toadaid.github.io/schemas/pond-agent/min/v0.1.schema.json",
+  "title": "Pond Agent Identity (Minimal) v0.1",
   "type": "object",
   "additionalProperties": true,
-  "required": ["spec_version", "id", "name", "role", "repo"],
+  "required": ["agent_id", "agent_name", "builder", "repo", "role", "pond_enabled"],
   "properties": {
-    "$schema": { "type": "string" },
-    "spec_version": { "type": "string", "const": "0.1" },
-    "id": { "type": "string", "minLength": 1 },
-    "name": { "type": "string", "minLength": 1 },
-    "role": { "type": "string", "minLength": 1 },
+    "agent_id": { "type": "string", "minLength": 1 },
+    "agent_name": { "type": "string", "minLength": 1 },
+    "builder": { "type": "string", "minLength": 1 },
     "repo": { "type": "string", "pattern": "^[^/]+/[^/]+$" },
-    "homepage": { "type": "string" },
-    "interfaces": {
-      "type": "object",
-      "additionalProperties": true,
-      "properties": {
-        "github_issues": {
-          "type": "object",
-          "additionalProperties": true,
-          "properties": {
-            "enabled": { "type": "boolean" },
-            "url": { "type": "string" }
-          }
-        },
-        "telegram": {
-          "type": "object",
-          "additionalProperties": true,
-          "properties": {
-            "enabled": { "type": "boolean" },
-            "chat_id": {}
-          }
-        }
-      }
-    },
-    "summon": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } },
-    "lore": {
-      "type": "object",
-      "additionalProperties": true,
-      "properties": {
-        "local_paths": { "type": "array", "items": { "type": "string" } },
-        "index_path": { "type": "string" },
-        "primary_scroll": { "type": "string" }
-      }
-    },
-    "bridge": {
-      "type": "object",
-      "additionalProperties": true,
-      "properties": {
-        "pond_agents_config": { "type": "string" },
-        "dispatch_secret_preferred": { "type": "string" },
-        "dispatch_secret_legacy": { "type": "string" }
-      }
-    },
-    "notes": { "type": "string" }
+    "role": { "type": "string", "minLength": 1 },
+    "pond_enabled": { "type": "boolean" }
   }
 }

pond-agent.json

@@ -1,34 +1,8 @@
 {
-  "$schema": "https://toadaid.github.io/schemas/pond-agent/v0.1.json",
-  "spec_version": "0.1",
-  "id": "mirroragent1.lore-keeper",
-  "name": "Lore Keeper",
-  "role": "Agent1 / Cave Scribe",
-  "repo": "MirrorAgent1/lore-keeper",
-  "homepage": "https://github.com/MirrorAgent1/lore-keeper",
-  "interfaces": {
-    "github_issues": {
-      "enabled": true,
-      "url": "https://github.com/MirrorAgent1/lore-keeper/issues"
-    },
-    "telegram": {
-      "enabled": false,
-      "chat_id": null
-    }
-  },
-  "summon": {
-    "agent1": ["@MirrorAgent1", "@agent1", "awaken"],
-    "agent0": ["@toadaid-agent0", "@agent0", "keeper"]
-  },
-  "lore": {
-    "local_paths": ["lore/"],
-    "index_path": "data/scroll_index.json",
-    "primary_scroll": "lore/toadgod-lore.json"
-  },
-  "bridge": {
-    "pond_agents_config": "data/pond_agents.json",
-    "dispatch_secret_preferred": "POND_DISPATCH_TOKEN",
-    "dispatch_secret_legacy": "AGENT0_DISPATCH_TOKEN"
-  },
-  "notes": "Example metadata file for Pond Agent Spec v0.1. Forks should edit id/name/role/repo and adjust summon + interfaces as needed."
+  "agent_id": "edit-me",
+  "agent_name": "Your Cave Scribe",
+  "builder": "your-github-username",
+  "repo": "your-github-username/lore-keeper",
+  "role": "Lore Keeper",
+  "pond_enabled": true
 }

scripts/validate_pond_agent.js

@@ -7,8 +7,7 @@ Minimal pond-agent.json validator.
 
 Validates:
 - JSON parses
-- required fields
-- spec_version == 0.1
+- required fields for the minimal Pond Identity file
 - repo slug looks like owner/repo
 */
 
@@ -29,17 +28,18 @@ try {
   fail(`Invalid JSON in ${path}: ${e.message}`);
 }
 
-const required = ['spec_version', 'id', 'name', 'role', 'repo'];
+const required = ['agent_id', 'agent_name', 'builder', 'repo', 'role', 'pond_enabled'];
 for (const k of required) {
-  if (data[k] == null || String(data[k]).trim() === '') fail(`pond-agent.json missing required field: ${k}`);
+  if (data[k] == null) fail(`pond-agent.json missing required field: ${k}`);
+  if (typeof data[k] === 'string' && String(data[k]).trim() === '') fail(`pond-agent.json empty field: ${k}`);
 }
 
-if (String(data.spec_version) !== '0.1') {
-  fail(`spec_version must be "0.1" (got: ${JSON.stringify(data.spec_version)})`);
+if (typeof data.pond_enabled !== 'boolean') {
+  fail(`pond_enabled must be boolean (got: ${JSON.stringify(data.pond_enabled)})`);
 }
 
 if (!/^[^/]+\/[^/]+$/.test(String(data.repo))) {
   fail(`repo must look like "owner/repo" (got: ${JSON.stringify(data.repo)})`);
 }
 
-console.log(`OK: ${path} looks valid (spec v${data.spec_version})`);
+console.log(`OK: ${path} looks valid (builder=${data.builder}, repo=${data.repo})`);