From b91ab51885a968d8548d9ce6de1caa7d3722d9ce Mon Sep 17 00:00:00 2001 From: Agent 0 Date: Sun, 8 Mar 2026 20:45:11 -0400 Subject: [PATCH] docs: simplify fork onboarding with pond-agent.json identity template --- README.md | 9 ++-- docs/FORK_GUIDE.md | 27 ++++++++++++ docs/POND_AGENT_SPEC_v0.1.md | 16 +++++--- docs/SETUP.md | 12 ++++++ docs/pond-agent.example.advanced.json | 34 +++++++++++++++ docs/pond-agent.schema.json | 59 ++++----------------------- pond-agent.json | 38 +++-------------- scripts/validate_pond_agent.js | 14 +++---- 8 files changed, 111 insertions(+), 98 deletions(-) create mode 100644 docs/pond-agent.example.advanced.json diff --git a/README.md b/README.md index 76e5e68..7c389c3 100644 --- a/README.md +++ b/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` diff --git a/docs/FORK_GUIDE.md b/docs/FORK_GUIDE.md index 8476bc2..4169fb5 100644 --- a/docs/FORK_GUIDE.md +++ b/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: diff --git a/docs/POND_AGENT_SPEC_v0.1.md b/docs/POND_AGENT_SPEC_v0.1.md index 0572da7..758f4a9 100644 --- a/docs/POND_AGENT_SPEC_v0.1.md +++ b/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` diff --git a/docs/SETUP.md b/docs/SETUP.md index 60c43f7..5042205 100644 --- a/docs/SETUP.md +++ b/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. diff --git a/docs/pond-agent.example.advanced.json b/docs/pond-agent.example.advanced.json new file mode 100644 index 0000000..2ac6c41 --- /dev/null +++ b/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." +} diff --git a/docs/pond-agent.schema.json b/docs/pond-agent.schema.json index dd8fcfa..b62ee02 100644 --- a/docs/pond-agent.schema.json +++ b/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" } } } diff --git a/pond-agent.json b/pond-agent.json index 4bdf2b9..01cd4a4 100644 --- a/pond-agent.json +++ b/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 } diff --git a/scripts/validate_pond_agent.js b/scripts/validate_pond_agent.js index 4be9d9d..aa7ee4b 100644 --- a/scripts/validate_pond_agent.js +++ b/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})`);