docs: artifact-location rule + CONTRIBUTING for community growth

The whole point of this project is that the agent's growth is shareable.
If skills and extensions silently land in ~/.pi/ on the maintainer's
laptop, every clone starts from zero and the repo becomes a fancy
README. Fix that with an explicit hard rule and a contributor guide.

- AGENTS.md: new "Artifact location — hard rule" subsection spelling out
  that skills/extensions/prompts/state/.pi-settings ALL live in this repo,
  never in ~/.pi/. Pi's own built-in skills (skill-creator, etc.) stay
  user-global; the agent may use them, but their *output* must land here.
- README: new "Everything in the repo" subsection covering the same rule
  in user-facing language, plus a pointer to CONTRIBUTING.md.
- CONTRIBUTING.md (new): skill/extension formats, server-agnostic and
  no-secrets requirements, smoke-test recipe, PR checklist.
- .gitignore: switch from blanket `.pi/` ignore to `.pi/*` + explicit
  un-ignore of `.pi/settings.json`, so project Pi config is reproducible.
- "Don't push without operator confirmation" → "without human
  confirmation via the repo" — consistent with the new control model.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.gitignore

@@ -10,8 +10,11 @@ yarn-debug.log*
 yarn-error.log*
 pnpm-debug.log*
 
-# Pi runtime state — sessions, caches, locally-installed extensions
-.pi/
+# Pi runtime state — sessions and cache are local-only.
+.pi/*
+# …but commit .pi/settings.json — it's the project's Pi config (installed
+# extensions, model defaults, etc.) and must be reproducible across clones.
+!.pi/settings.json
 sessions/
 *.session.json
 

AGENTS.md

@@ -55,11 +55,25 @@ When you encounter a missing capability, your loop is:
 
 1. **Decide** whether the capability is one-off (handle inline) or reusable (codify).
 2. If reusable, create either:
-   - a **skill** under `skills/<short-name>.md` — markdown, with a frontmatter header (`name`, `description`, `when_to_use`) and a procedural body.
-   - or an **extension** under `extensions/<short-name>.ts` — for anything that needs to register a real Pi tool or hook into Mineflayer events.
-3. Commit the new file with a clear message. The repo is on `main`. Don't push without operator confirmation.
+   - a **skill** under `./skills/<short-name>.md` — markdown, with a frontmatter header (`name`, `description`, `when_to_use`) and a procedural body.
+   - or an **extension** under `./extensions/<short-name>.ts` — for anything that needs to register a real Pi tool or hook into Mineflayer events.
+3. Commit the new file with a clear message. The repo is on `main`. Don't push without human confirmation via the repo.
 4. Update `README.md`'s **Status** section as milestones land.
 
+### Artifact location — hard rule
+
+Everything you author lives **in this repo**, never in `~/.pi/` or any other user-global location. This is what makes the project shareable:
+
+- **Skills** → `./skills/<name>.md`. Not `~/.pi/skills/`. Not `~/.pi/agent/`.
+- **Extensions** → `./extensions/<name>.{ts,js}`. Not globally `npm install`-ed.
+- **Prompt templates** → `./prompts/<name>.md`. Not `~/.pi/prompts/`.
+- **Per-session learnings, world state, base coords, etc.** → `./state/<MC_HOST>/...`. Gitignored by default, but **lives inside the repo**.
+- **Pi project settings** → `./.pi/settings.json` (use `pi install -l <source>`, the `-l` makes it project-local). This file IS committed; without it a fresh clone can't reproduce your tool stack.
+
+If you need to use Pi's built-in `skill-creator` or similar global tools, that's fine — just make sure the *output* lands under `./skills/` in this repo.
+
+If something genuinely belongs in the user's global Pi config (a personal API key, a workflow only the human cares about), don't write it. Tell the human and let them decide.
+
 Skills you might want early on (good for any server):
 
 - `server-onboarding` — what auth flow this server uses; relogin / autologin pattern.

CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing
+
+This repo grows by accretion — skills, extensions, and prompts written by Pi agents (or humans) playing on real Minecraft servers. PRs welcome.
+
+## What you can contribute
+
+| Kind | Where | When |
+|---|---|---|
+| **Skill** | `skills/<name>.md` | You taught the agent a useful procedure (login flow, recovery routine, farming loop, etc.) and want others to skip the discovery cost. |
+| **Extension** | `extensions/<name>.{ts,js}` | The skill needs real code — a new Pi tool, a Mineflayer plugin wrapper, an event subscription. |
+| **Prompt template** | `prompts/<name>.md` | A reusable kickoff or tick prompt that works across servers. |
+| **Docs** | `README.md`, `docs/*.md`, `AGENTS.md` | Clarifications, new safety rules, architecture notes. |
+
+If you change `AGENTS.md`, treat it as load-bearing — every agent that clones the repo starts from it. Discuss in a PR first.
+
+## Skill format
+
+A skill is a single Markdown file with YAML frontmatter:
+
+```markdown
+---
+name: <short-kebab-case-slug>
+description: <one-sentence summary; Pi uses this to decide whether to load the skill>
+when_to_use: <one-sentence trigger; when in a session should the agent reach for this?>
+---
+
+# <Skill title>
+
+## Steps
+
+1. ...
+2. ...
+
+## Notes
+
+- Edge cases, gotchas, known failure modes.
+```
+
+Keep skills short (under ~150 lines). If it gets longer, split into multiple skills that reference each other, or promote part of it to an extension.
+
+## Extension format
+
+Extensions are TypeScript (preferred) or JavaScript modules. See `pi.dev/docs/latest` for the current extension API. Project-local install:
+
+```bash
+pi install -l ./extensions/your-extension.ts
+```
+
+The `-l` flag writes to `./.pi/settings.json` (committed) so a fresh clone gets the same toolset.
+
+## Hard rules
+
+- **Server-agnostic.** No `play.xmatic.team`, no specific nicknames, no AuthMe password in any committed file. Everything that varies per server lives in `.env`.
+- **No secrets in git.** If you have to think about whether something is a secret, it is. Run `git diff --staged` before every commit.
+- **No global writes.** Skills, extensions, and Pi settings all live under this repo's tree, not under `~/.pi/`. See `AGENTS.md` → *Artifact location*.
+- **Don't loosen safety.** The hard rules in `AGENTS.md` (no OP, no griefing, no chat-as-control, rate limits) are non-negotiable. PRs that weaken them get closed.
+
+## Testing a skill / extension
+
+Quick smoke test before opening a PR:
+
+```bash
+# 1. Fresh clone in a temp dir
+git clone git@github.com:xmatic-squad/pepa-pi-bot.git /tmp/pepa-test
+cd /tmp/pepa-test
+
+# 2. Minimal config — point at a throwaway local MC server if you have one
+cp .env.example .env
+$EDITOR .env
+
+# 3. Install deps
+npm install
+
+# 4. Run Pi and ask it to dry-run your skill
+pi
+# > Please list the loaded skills. Then describe what skills/your-new-skill.md
+# > would do, step-by-step, without actually executing it.
+```
+
+If Pi can't even *find* your skill, the frontmatter is wrong — check `name:` is a valid slug and the file is under `./skills/`.
+
+## PR checklist
+
+- [ ] File lives in the correct directory (`skills/`, `extensions/`, `prompts/`, `docs/`).
+- [ ] Frontmatter is valid YAML; `name` matches the filename.
+- [ ] No hard-coded server hostnames, nicknames, passwords, or API keys.
+- [ ] `README.md`'s Status section updated if this is a user-facing milestone.
+- [ ] Commit message is descriptive (`feat(skill): add respawn-and-return for survival servers`).
+
+## License
+
+By contributing you agree that your work is released under the project's [MIT License](./LICENSE).

README.md

@@ -104,7 +104,7 @@ You can mix providers via `--provider openai --model gpt-5` at launch — cheape
 Pi has first-class support for three growth surfaces:
 
 - **`skills/`** — Markdown-defined capabilities Pi can invoke. The agent can `Write` new ones at runtime when it discovers a missing capability.
-- **`extensions/`** — TypeScript modules registering new tools, commands, or UI tweaks. Installed via `pi install npm:<pkg>` / `pi install git:<url>` or written in-tree.
+- **`extensions/`** — TypeScript modules registering new tools, commands, or UI tweaks. Installed project-locally via `pi install -l npm:<pkg>` / `pi install -l git:<url>`, or written in-tree.
 - **`prompts/`** — Reusable prompt templates. Useful for cron-driven tick prompts ("what should I do next minute?").
 
 The opening `AGENTS.md` instructs the agent to start by writing a `mineflayer-bridge` extension that can:
@@ -116,6 +116,14 @@ The opening `AGENTS.md` instructs the agent to start by writing a `mineflayer-br
 
 Everything beyond that — farming, exploration, base-building, player interaction, server-specific quirks — should emerge from the agent itself.
 
+### Everything in the repo
+
+A hard rule, mirrored in `AGENTS.md`: every artefact the agent produces **lives in this repo**, never in the user's `~/.pi/` directory. That includes skills, extensions, prompt templates, project Pi settings (`.pi/settings.json`), and per-server state (`state/<MC_HOST>/`).
+
+The point is reproducibility and **community growth**: a fresh `git clone` should bring along every skill any contributor has written. Pi's own built-in skills (`skill-creator`, `agent-browser`, etc.) stay user-global — the agent is allowed to *use* them, but anything it *authors* lands under `./skills/` or `./extensions/` here.
+
+See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the skill format and how to propose changes.
+
 ## Project layout
 
 ```