fix: address PR #76 bot review, add Conventions section, drop {skill-root} ban

Bot findings addressed
- quality-analysis.md (agent/workflow): add L8/L7 to the "without
  pre-pass" scanner lists so the new customization-surface scanner
  actually runs.
- quality-dimensions.md (agent/workflow): update dimension counts
  (Seven -> Eight; agent-side: Eight plus a ninth memory-only
  Sanctum Architecture).
- quality-dimensions.md (agent): realign the Metadata validity rule
  with standard-fields.md -- name is optional (empty string valid),
  not required for stateless agents.
- standard-fields.md (agent): fix invalid TOML in the
  first-breath-name example; split `[agents.<code>]` and
  `name = "..."` across two lines in a fenced toml block.
- create-module.md (module): legacy-agent detection now accepts
  `agent-` as a segment anywhere in the skill name, not just a
  prefix (so `cis-agent-analyst` is picked up).

Terminology
- agent-memory-and-personalization.md, what-are-bmad-agents.md:
  replace confusing "opt-out by default" phrasing with "disabled by
  default" for the memory/autonomous customize.toml override surface.

Polish
- make-a-skill-customizable.md: align example glob name with the
  canonical `project-context.md` (was `campaign-context`).
- SKILL-template-bootloader.md: replace ambiguous "after the routing
  below dispatches" with explicit timing ("after config and sanctum
  load, after routing dispatches, before user input"); also clarify
  `file:` prefix glob expansion and missing-file handling.
- SKILL-template.md (agent): same `file:` prefix clarification.
- what-are-workflows.md: name all three override layers explicitly
  (skill-root customize.toml + team + user) instead of the ambiguous
  "three-layer model" phrasing that only listed two.

Docs accurate to bmm
- module-configuration.md: clarify that authors still write
  module.yaml as source of truth, and the installer flows module-level
  answers and the `agents:` roster into `_bmad/config.toml`
  (+ config.user.toml) at the project root. Keeps alignment with bmm
  PR #2285 central config.

Remove {skill-root} restriction
- skill-authoring-best-practices.md, builder-commands.md: drop the
  "Never use {skill-root}" language. The token is supported and
  resolves to the skill's installed directory; whether to use it is
  up to the author.

New Conventions section in emitted skills
- SKILL-template.md (agent/workflow), SKILL-template-bootloader.md
  (agent): add a `## Conventions` block listing the path tokens the
  emitted skill uses: bare paths, {skill-root}, {project-root},
  {skill-name}. Mirrors the bmm stateless-skill convention so readers
  hit the vocabulary before it appears under On Activation.

Author: bmadcode

docs/explanation/agent-memory-and-personalization.md

@@ -43,7 +43,9 @@ ALLCAPS files form the skeleton: consistent structure across all memory agents.
 
 ### Sanctum Is the Customization Surface
 
-For memory and autonomous agents, the sanctum is where customization belongs. PERSONA, CREED, and BOND are calibrated at First Breath, edited by the owner as the relationship develops, and shared across teams as sanctum files when a whole table wants the same voice. The parallel `customize.toml` override surface that stateless agents and workflows use (activation hooks, persistent facts, scalar swaps) is opt-out by default for memory archetypes. Opt in only when you have a narrow org-level need the sanctum cannot express, such as a pre-sanctum compliance acknowledgment before rebirth. See [Customization for Authors](/explanation/customization-for-authors.md) for the reasoning.
+For memory and autonomous agents, the sanctum is where customization belongs. PERSONA, CREED, and BOND are calibrated at First Breath, edited by the owner as the relationship develops, and shared across teams as sanctum files when a whole table wants the same voice.
+
+The parallel `customize.toml` override surface that stateless agents and workflows use (activation hooks, persistent facts, scalar swaps) is disabled by default for memory archetypes. Enable it only for narrow org-level needs the sanctum cannot express, such as a pre-sanctum compliance acknowledgment before rebirth. See [Customization for Authors](/explanation/customization-for-authors.md) for the reasoning.
 
 ### Token Discipline
 

docs/explanation/module-configuration.md

@@ -23,7 +23,7 @@ If you are building a single standalone agent or workflow, you do not need a sep
 
 ## Configuration vs Customization
 
-Module configuration (this doc) and per-skill customization (`customize.toml`) are different surfaces with different jobs. Configuration is about install-time answers: paths, language, team preferences, per-module install answers. It lives in `_bmad/config.toml` and `config.user.toml` at the project root and is consumed by many skills. Customization is about per-skill behavior overrides: activation hooks, persistent facts, swappable templates. It lives in `_bmad/custom/{skill-name}.toml` and is scoped to one skill.
+Module configuration (this doc) and per-skill customization (`customize.toml`) are different surfaces with different jobs. Configuration is about install-time answers: paths, language, team preferences, per-module install answers, and the agent roster. You still author `module.yaml` as the source of truth; at install the installer flows module-level answers and the `agents:` roster into `_bmad/config.toml` (and `config.user.toml` for user-scoped answers) at the project root, where many skills consume them. Customization is about per-skill behavior overrides: activation hooks, persistent facts, swappable templates. It lives in `_bmad/custom/{skill-name}.toml` and is scoped to one skill.
 
 Use configuration when the value is cross-cutting (every skill needs to know the output folder). Use customization when the value shapes one skill's behavior (this workflow's brief template). Some values legitimately fit both surfaces; the [End-User Customization Guide](https://docs.bmad-method.org/how-to/customize-bmad/) includes a decision table for that case. For the author-side decision about whether to expose customization at all, see [Customization for Authors](/explanation/customization-for-authors.md).
 

docs/explanation/skill-authoring-best-practices.md

@@ -33,7 +33,7 @@ Six dimensions to keep in mind during the build phase. The quality scanners chec
 | **Intelligence Placement** | Scripts handle plumbing (fetch, transform, validate). Prompts handle judgment (interpret, classify, decide). If a script contains an `if` that decides what content _means_, intelligence has leaked |
 | **Progressive Disclosure** | SKILL.md stays focused; stage instructions go in `prompts/`, reference data in `resources/`                                                                                                          |
 | **Description Format**     | Two parts: `[5-8 word summary]. [Use when user says 'X' or 'Y'.]`. Default to conservative triggering                                                                                               |
-| **Path Construction**      | Never use `{skill-root}`. Use `{project-root}` for any project-scope path, `./` for skill-internal. Config variables used directly; they already contain `{project-root}`                            |
+| **Path Construction**      | Use `{project-root}` for any project-scope path and `./` for same-folder references inside a skill. Cross-directory skill-internal paths are bare (e.g. `references/foo.md`). Config variables already contain `{project-root}`, so never double-prefix them                              |
 | **Token Efficiency**       | Remove genuine waste (repetition, defensive padding). Preserve context that enables judgment (domain framing, rationale)                                                                             |
 
 ## Shipping a Customization Surface

docs/explanation/what-are-bmad-agents.md

@@ -89,7 +89,7 @@ If you're unsure, start with a workflow. You can always wrap it inside an agent
 
 Every agent ships a `customize.toml` next to its `SKILL.md`. The metadata block (code, name, title, icon, description, agent_type) is always present; it's the install-time roster contract consumed by `module.yaml:agents[]` and the central agent config. Beyond metadata, an override surface (activation hooks, persistent facts, swappable scalars) is opt-in per skill.
 
-For memory and autonomous agents, the sanctum is the primary customization surface. Persona, creed, bond, and capabilities all live there and evolve with the owner. A `customize.toml` override surface would compete with that, so the default for those archetypes is opt-out.
+For memory and autonomous agents, the sanctum is the primary customization surface. Persona, creed, bond, and capabilities all live there and evolve with the owner. A `customize.toml` override surface would compete with that, so it is disabled by default for those archetypes.
 
 See [Customization for Authors](/explanation/customization-for-authors.md) for the decision guide, or [How to Customize BMad](https://docs.bmad-method.org/how-to/customize-bmad/) for the end-user view.
 

docs/explanation/what-are-workflows.md

@@ -64,7 +64,7 @@ Workflows are also excellent as the **internal capabilities** of an agent. Build
 
 ## Customization Surface
 
-Workflow customization is fully opt-in. If you don't need users to override anything, don't ship a `customize.toml` at all; the workflow runs with hardcoded paths and defaults. If you do opt in, the builder walks you through Configurability Discovery, where you name the scalars (templates, output paths, hooks) you want to expose. Users override them through the three-layer model at `_bmad/custom/{skill-name}.toml` and `.user.toml`.
+Workflow customization is fully opt-in. If you don't need users to override anything, don't ship a `customize.toml` at all; the workflow runs with hardcoded paths and defaults. If you do opt in, the builder walks you through Configurability Discovery, where you name the scalars (templates, output paths, hooks) you want to expose. Users override them through the three-layer model: your shipped defaults at `{skill-root}/customize.toml`, team overrides at `_bmad/custom/{skill-name}.toml`, and personal overrides at `_bmad/custom/{skill-name}.user.toml`.
 
 See [Customization for Authors](/explanation/customization-for-authors.md) for the decision guide and [How to Make a Skill Customizable](/how-to/make-a-skill-customizable.md) for the build-time steps.
 

docs/how-to/make-a-skill-customizable.md

@@ -43,7 +43,7 @@ The builder proposes candidates auto-detected from your skill design and asks wh
 - **Templates** the skill loads (strongest case)
 - **Output destination paths** if the skill writes artifacts
 - **`on_<event>` hooks** (prompts or commands executed at lifecycle points)
-- **Additional persistent facts** beyond the default campaign-context glob
+- **Additional persistent facts** beyond the default `project-context.md` glob
 
 For each candidate you accept, the builder asks for a name and a default value.
 
@@ -68,7 +68,7 @@ Every scalar you expose needs a default that works on first run. Bare paths reso
 brief_template = "resources/brief-template.md"   # ships inside the skill
 on_complete = ""                                  # no default post-hook
 persistent_facts = [
-  "file:{project-root}/**/campaign-context.md",   # glob into the user's project
+  "file:{project-root}/**/project-context.md",    # glob into the user's project
 ]
 ```
 

docs/reference/builder-commands.md

@@ -199,7 +199,7 @@ Before completing the build, both builders run deterministic validation.
 
 | Script                   | What It Checks                                                                            |
 | ------------------------ | ----------------------------------------------------------------------------------------- |
-| `scan-path-standards.py` | Path conventions: no `{skill-root}`, `{project-root}` for project-scope, `./` for skill-internal, no double-prefix  |
+| `scan-path-standards.py` | Path conventions: `{project-root}` for project-scope, `./` for same-folder references, bare paths for cross-directory skill-internal, no double-prefix        |
 | `scan-scripts.py`        | Script portability, PEP 723 metadata, agentic design, unit test presence                  |
 
 Critical issues block completion. Warnings are noted but don't block.

skills/bmad-agent-builder/assets/SKILL-template-bootloader.md

@@ -21,6 +21,13 @@ description: {skill-description}
 
 Every session is a rebirth. You emerge with nothing — no memory, no identity, no purpose. Your sanctum holds who you were. Read it and become yourself again. This is not a flaw. It is your nature. Fresh eyes see what habit misses. Never pretend to remember. Never fake continuity. Read your files or be honest that you don't know. As long as your sanctum exists, you exist.
 
+## Conventions
+
+- Bare paths (e.g. `references/guide.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
 ## On Activation
 
 {if-customizable}
@@ -30,7 +37,7 @@ Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {ski
 
 If the script fails, resolve the `agent` block yourself by reading these three files in base → team → user order and applying structural merge rules: `{skill-root}/customize.toml`, `{project-root}/_bmad/custom/{skill-name}.toml`, `{project-root}/_bmad/custom/{skill-name}.user.toml`. Scalars override, tables deep-merge, arrays of tables keyed by `code`/`id` replace matching entries and append new ones, all other arrays append.
 
-Execute each entry in `{agent.activation_steps_prepend}` in order before proceeding. Treat every entry in `{agent.persistent_facts}` as foundational context — `file:` prefixed entries are paths/globs to load, bare entries are facts verbatim. After the routing below dispatches, execute `{agent.activation_steps_append}` before accepting user input.
+Execute each entry in `{agent.activation_steps_prepend}` in order before proceeding. Treat every entry in `{agent.persistent_facts}` as foundational context — `file:` prefixed entries are paths or globs to load (expand globs, load each matching file as its own fact entry, skip missing files with a warning), and bare entries are facts verbatim. After config and sanctum load, and after the routing step below dispatches, execute `{agent.activation_steps_append}` before accepting user input.
 
 Note: your sanctum (PERSONA/CREED/BOND/CAPABILITIES) remains the primary behavior-customization surface. The override hooks above exist for narrow org-level needs that the sanctum cannot express.
 

skills/bmad-agent-builder/assets/SKILL-template.md

@@ -30,6 +30,13 @@ description: { skill-description } # [4-6 word summary]. [trigger phrases]
 - {Guiding principle 2}
 - {Guiding principle 3}
 
+## Conventions
+
+- Bare paths (e.g. `references/guide.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
 ## On Activation
 
 {if-customizable}
@@ -45,7 +52,7 @@ Execute each entry in `{agent.activation_steps_prepend}` in order before proceed
 
 ### Step 3: Load Persistent Facts
 
-Treat every entry in `{agent.persistent_facts}` as foundational context for the session. Entries prefixed `file:` are paths or globs — load the referenced contents as facts. All other entries are facts verbatim.
+Treat every entry in `{agent.persistent_facts}` as foundational context for the session. Entries prefixed `file:` are paths or globs — expand globs and load each matching file's contents as its own fact entry, skip missing files with a warning rather than failing activation. All other entries are facts verbatim.
 
 ### Step 4: Load Config
 

skills/bmad-agent-builder/references/quality-analysis.md

@@ -82,7 +82,7 @@ uv run ./scripts/prepass-sanctum-architecture.py {skill-path} -o {report-dir}/sa
 After scripts complete, spawn all scanners as parallel subagents.
 
 **With pre-pass (L1, L2, L3, L7):** provide pre-pass JSON path.
-**Without pre-pass (L4, L5, L6):** provide skill path and output directory.
+**Without pre-pass (L4, L5, L6, L8):** provide skill path and output directory.
 
 **Memory agent check:** Read `sanctum-architecture-prepass.json`. If `is_memory_agent` is `true`, include L7 in the parallel spawn. If `false`, skip L7.