docs(.agents): add AGENTS.md — directory map and override pattern

Documents every folder under .agents/, what it contains, and the
override-by-same-name pattern. Explains YOLO as a flag not a mode.

is globally ignored but the spec file under .agents/ must be tracked.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.agents/AGENTS.md

@@ -0,0 +1,63 @@
+# .agents/
+
+Agent configuration for this repository following the
+[AGENTS-1 spec](https://github.com/agentsfolder/spec).
+
+This folder is the **override and extension layer only**. SF's built-in
+defaults (modes, skills, policies) apply automatically. Files here exist
+only when the project needs to override or add something.
+
+## Structure
+
+```
+.agents/
+  AGENTS.md         ← this file
+  manifest.yaml     ← specVersion, defaults (mode/policy), enabled policies + skills
+  prompts/
+    base.md         ← instructions injected into every agent turn
+    project.md      ← project-specific context: non-negotiables, workflow, build commands
+    snippets/       ← reusable prompt fragments included by modes
+      style.md      ← code style rules
+      principles.md ← invariants (DB-first, two modes, etc.)
+      non-goals.md  ← things SF explicitly will not do
+  modes/            ← project mode OVERRIDES only (add file with same name to override a default)
+  policies/
+    default-safe.yaml ← confirm destructive ops; deny .env/.ssh/db paths
+    yolo.yaml         ← no confirmations (YOLO flag); path denies still apply
+  skills/           ← project-specific skills + built-in overrides (same name = override)
+    forge-autonomous-runtime/ ← explains SF autonomous loop, UOK gates, recovery paths
+    forge-command-surface/    ← SF slash commands, browser command parity, headless dispatch
+    nix-build/                ← build any @singularity-forge/* package via nix develop
+    sf-wiki/                  ← override of built-in sf-wiki: use UPPERCASE filenames (.sf/ convention)
+    smoke-test/               ← run sf-run smoke tests (--version, --help, --print)
+  scopes/           ← path-based config overrides (empty — no path-specific overrides yet)
+  profiles/         ← named overlays e.g. "ci", "dev" (empty — no profiles yet)
+  schemas/          ← generated JSON schemas (not committed; tooling writes these)
+  state/
+    .gitignore      ← excludes state.yaml (per-developer convenience, never committed)
+```
+
+## Override pattern
+
+To override a built-in mode or skill, add a file with the **same name**:
+
+```
+# Override built-in sf-wiki skill
+.agents/skills/sf-wiki/SKILL.md
+
+# Override built-in build mode
+.agents/modes/build.md
+```
+
+Built-in defaults (ask, build, autonomous modes; all SF system skills) are
+provided by SF and do not need to be listed here.
+
+## Policies
+
+| Policy | When applied |
+|--------|-------------|
+| `default-safe` | Default — confirms destructive ops, denies secrets paths |
+| `yolo` | When YOLO flag is active (`Ctrl+Y` / `/mode yolo`) — removes confirmations, path denies still apply |
+
+YOLO is a **flag** on top of Build or Autonomous, not a mode. It is not a
+Shift+Tab stop.

.gitignore

@@ -68,6 +68,7 @@ dist/
 .sf*.tgz
 .artifacts/
 AGENTS.md
+!.agents/AGENTS.md
 .bg-shell/
 TODOS.md
 .planning/