docs: repository README, contributor rules, scenario template and authoring guide

README leads with the finding that motivated the repository -- pi emits the
skills section only when a tool named 'read' is active, so Curator's
--no-tools --skill combination made its policy unreachable -- with the measured
before/after table and instructions to reproduce it at zero token cost.

AGENTS.md sets seven rules for anyone changing this repository. The third is the
one that matters most: verify pi's behaviour with a probe rather than inferring it
from the docs. Three claims in the first draft of these documents were wrong and
were only corrected by running one.

The _template scenario carries the isolation defaults and inline warnings at the
places where mistakes have already cost time: --no-tools disabling the skills
mechanism, cwd anchoring .pi discovery, the read override being mandatory rather
than optional, and allowed-tools frontmatter not being enforced in 0.84.3.

scenarios/_template/profile.toml

@@ -0,0 +1,79 @@
+# <scenario> — Pi scenario profile
+#
+# Copy this directory to scenarios/<name>/ and fill in every <PLACEHOLDER>.
+# This file is the single source of truth for the launch contract;
+# scripts/deploy-scenario.sh renders it into <workspace>/.pi/launch.json.
+#
+# Read docs/isolation-baseline.md before changing anything under [isolation].
+
+[scenario]
+name        = "<name>"
+description = "<one sentence: what this agent is for>"
+workspace   = "/home/claw/pi-workspaces/<name>"
+session_dir = "/home/claw/.local/share/pi-<name>/sessions"
+service     = "<name>.service"        # empty if launched by hand
+# "managed": this repository is authoritative and --apply is allowed.
+# "mirror":  this file records a live configuration; --apply is refused.
+deploy      = "managed"
+
+[model]
+provider = "zenmux"
+primary  = "<provider/model-id>"
+fallback = ""                          # must also exist in runtime/agent/models.json.template
+
+[model.thinking]
+conversation = "high"
+extraction   = "low"
+synthesis    = "medium"
+
+[session]
+id_prefix             = "<name>"
+rotate_after_prompts  = 20
+rotate_after_messages = 50
+strategy              = "session-id"
+
+[isolation]
+# Defaults implement docs/isolation-baseline.md. Any `false` below widens what
+# the agent loads or can call and must be justified in a comment.
+no_builtin_tools    = true    # not --tools: a registry allowlist blocks dynamic tools
+no_extensions       = true
+no_skills           = true
+no_prompt_templates = true
+no_themes           = true
+no_context_files    = true    # the only switch that stops parent-dir AGENTS.md
+approve             = true    # required to load .pi/SYSTEM.md
+
+[personality]
+# Both are system-prompt files, unaffected by --no-context-files.
+system_prompt        = ".pi/SYSTEM.md"
+append_system_prompt = ".pi/APPEND_SYSTEM.md"
+context_files        = []
+
+[resources]
+extensions = [".pi/extensions/<name>-tools.ts"]
+skills     = [".pi/skills/<skill-name>"]
+
+[tools]
+# Enforced twice inside the extension: setActiveTools plus a tool_call block.
+# `read` is mandatory, not optional: pi emits the skills section only when a tool
+# named `read` is active, and skill bodies load through it.
+allow             = ["read"]
+structured_output = []
+receipt_tools     = []       # tools whose results are user-visible state changes
+
+[tools.read_policy]
+roots      = [".pi/skills"]  # must include the skill dirs or bodies are unloadable
+extensions = [".md"]
+max_chars  = 40000
+
+[budget]
+turn_deadline_seconds   = 180
+startup_timeout_seconds = 60
+
+[env]
+minimal   = true
+allowlist = ["PATH", "HOME", "LANG", "TZ"]
+extra     = []
+
+[secrets]
+env_file = ""