docs: add generic agent onboarding and handoff guidance

AGENTS.md

@@ -0,0 +1,69 @@
+# AGENTS.md
+
+Repository-wide instructions for any autonomous or semi-autonomous coding agent.
+
+## Purpose
+
+This repository is intended to be reusable across many projects. Keep changes and documentation generic unless you are actively working inside a specific downstream repo that requires project-specific customization.
+
+## Startup checklist (every run)
+
+1. Read this file (`AGENTS.md`).
+2. Read `CLAUDE.md` for operating conventions.
+3. Read `CONTRIBUTING.md` for commit/PR quality expectations.
+4. Check `KNOWN_ISSUES.md` before making changes.
+5. If present, check `docs/agent-handoffs/` for recent agent learnings.
+
+## Generic-first policy
+
+- Do not hardcode organization, product, customer, or brand-specific details.
+- Do not assume a single deployment environment unless explicitly configured.
+- Prefer neutral names such as `project`, `service`, `integration`, `consumer`, `provider`.
+- Add project-specific notes only when working in that project's repo and label them clearly.
+
+## Agent learning + handoff protocol
+
+Agents are expected to leave concise, reusable notes for later agents.
+
+### Where to write
+
+- `docs/agent-handoffs/README.md` for folder usage.
+- `docs/agent-handoffs/learnings/` for new practical learnings.
+- `docs/agent-handoffs/incidents/` for issue/incident writeups and mitigations.
+
+### Naming convention
+
+Use generic, descriptive filenames:
+
+- `YYYY-MM-DD-short-topic.md` (example: `2026-02-14-lock-timeout-tuning.md`)
+
+Avoid brand, team, or person-specific prefixes in filenames.
+
+### Required note structure
+
+Each note should contain:
+
+- Context
+- Observation
+- Action taken
+- Validation performed
+- Recommendation for next agents
+
+Keep each note short and actionable.
+
+## Safety and quality baseline
+
+- Make smallest safe change first.
+- Prefer explicit commands over assumptions.
+- Validate with available tests/checks.
+- If blocked by environment limits, document the blocker and fallback.
+
+## Priority order
+
+When instructions conflict, follow this order:
+
+1. System/developer/user instructions in-session
+2. `AGENTS.md`
+3. `CLAUDE.md`
+4. `CONTRIBUTING.md`
+5. Inline comments and prompt files

CLAUDE.md

@@ -0,0 +1,42 @@
+# CLAUDE.md
+
+Operational playbook for agent execution in this repository.
+
+## Scope
+
+Applies to all agent tasks unless superseded by direct runtime instructions.
+
+## Operating model
+
+- Keep output and changes generic by default.
+- Prefer deterministic, auditable steps.
+- Record decisions so future agents can continue with minimal rediscovery.
+
+## Handoff documentation workflow
+
+When you learn something that can help future agents:
+
+1. Check for existing related notes in `docs/agent-handoffs/learnings/` and `docs/agent-handoffs/incidents/`.
+2. If the learning is new, add a small markdown note using the naming standard in `AGENTS.md`.
+3. Link related issue patterns in `KNOWN_ISSUES.md` when applicable.
+4. Keep note content sanitized and reusable (no secrets, no user-identifying details).
+
+## What belongs where
+
+- `KNOWN_ISSUES.md`: currently active/reproducible issues and known workarounds.
+- `docs/agent-handoffs/learnings/`: durable implementation insights and successful patterns.
+- `docs/agent-handoffs/incidents/`: failure reports, root-cause notes, and prevention guidance.
+- `CONTRIBUTING.md`: process standards for proposing and reviewing changes.
+
+## Style for agent notes
+
+- Prefer bullets over long prose.
+- Include exact commands where useful.
+- State confidence and remaining uncertainty.
+- End with a “Next agent should …” line.
+
+## Anti-patterns
+
+- Avoid repo-local jargon in shared templates.
+- Avoid stale TODO dumps without context or owner.
+- Avoid project/brand-specific terms unless explicitly required by the active repo.

CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# CONTRIBUTING
+
+Guidelines for humans and agents proposing changes.
+
+## Change principles
+
+- Keep changes focused and minimal.
+- Explain why a change is needed, not only what changed.
+- Preserve generic behavior unless implementing explicit repo-specific requirements.
+
+## Before opening a PR
+
+1. Confirm instructions in `AGENTS.md` and `CLAUDE.md` were followed.
+2. Run relevant checks/tests.
+3. Update docs affected by behavior changes.
+4. If you discovered reusable information, add/update a note under `docs/agent-handoffs/`.
+
+## Commit guidance
+
+- Use clear, descriptive commit messages.
+- Keep unrelated edits in separate commits.
+- Avoid committing temporary debug code or local-only artifacts.
+
+## PR guidance
+
+Include:
+
+- Summary of what changed
+- Why it changed
+- Validation performed
+- Any known follow-ups
+
+If no tests were run, state why.
+
+## Documentation maintenance
+
+When changing workflows:
+
+- Update `KNOWN_ISSUES.md` for new known limitations/workarounds.
+- Add a learning note if the change uncovered a reusable pattern.

KNOWN_ISSUES.md

@@ -0,0 +1,26 @@
+# KNOWN ISSUES
+
+Track active, reproducible issues in a generic format.
+
+## How to use this file
+
+- Keep entries short and factual.
+- Remove resolved issues quickly.
+- Link to handoff/incident notes for deep details.
+
+## Entry template
+
+### [ISSUE-YYYYMMDD-brief-name]
+
+- **Status:** Open | Monitoring | Mitigated
+- **Area:** Scheduler | Locking | Dashboard | Docs | Other
+- **Symptom:**
+- **Trigger/Conditions:**
+- **Workaround:**
+- **Impact:**
+- **Related notes:** `docs/agent-handoffs/incidents/...`
+- **Last verified:** YYYY-MM-DD
+
+---
+
+_No active issues currently recorded._

README.md

@@ -41,7 +41,7 @@ npm run dashboard:serve
 - `src/nostr-lock.mjs` — Generic lock/check/list CLI
 - `src/docs/TORCH.md` — Protocol summary and usage
 - `src/prompts/` — Generic scheduler prompts and flow
-- `examples/bitvid/` — Bitvid-style scheduler overlay examples adapted for standalone TORCH paths
+- `examples/` — Optional scheduler overlay examples for adapting TORCH to downstream repositories
 - `dashboard/index.html` — Static lock dashboard
 
 ## CLI dependencies
@@ -89,5 +89,3 @@ NOSTR_LOCK_NAMESPACE=my-project \
 AGENT_PLATFORM=codex \
 node src/nostr-lock.mjs lock --agent docs-agent --cadence daily
 ```
-
-[Tip Jar](https://tipjar.bitvid.network/?n=npub15jnttpymeytm80hatjqcvhhqhzrhx6gxp8pq0wn93rhnu8s9h9dsha32lx)

docs/agent-handoffs/README.md

@@ -0,0 +1,19 @@
+# Agent Handoffs
+
+This folder stores reusable learnings that help future agents work faster and safer.
+
+## Folders
+
+- `learnings/`: patterns that worked and can be reused.
+- `incidents/`: failures, root causes, and prevention notes.
+
+## Filename format
+
+Use: `YYYY-MM-DD-short-topic.md`
+
+Examples:
+
+- `2026-02-14-command-ordering.md`
+- `2026-02-14-lock-timeout-regression.md`
+
+Keep names generic and descriptive.

docs/agent-handoffs/incidents/2026-02-14-example-incident.md

@@ -0,0 +1,7 @@
+# Example Incident: Missing Baseline Context
+
+- **Context:** Agent started editing without reviewing policy files first.
+- **Observation:** Resulting patch required rework to match repo standards.
+- **Action taken:** Re-read policy docs, reverted conflicting edits, reapplied changes correctly.
+- **Validation performed:** Compared final output to policy docs and reran checks.
+- **Recommendation for next agents:** Read `AGENTS.md` and `CLAUDE.md` first on every run to avoid avoidable churn.

docs/agent-handoffs/learnings/2026-02-14-example-learning.md

@@ -0,0 +1,7 @@
+# Example Learning: Validation Before Summary
+
+- **Context:** Multi-file documentation update.
+- **Observation:** Running quick checks before writing summaries catches avoidable mistakes.
+- **Action taken:** Ran status and diff checks before finalizing.
+- **Validation performed:** Confirmed expected files changed and no accidental edits were included.
+- **Recommendation for next agents:** Always run at least one verification command after edits and before committing.