apache · potiuk · Sep 19, 2026 · Sep 22, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -353,7 +353,7 @@ but an organization Magpie does not ship is resolved from an
 adopter-local copy under `.apache-magpie-overrides/organizations/<org>/`
 — maintained in the adopter's repo or vendored from the organization's
 own repo (discovery, never auto-fetch, per
-[`PRINCIPLES.md` §13](PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies)).
+[`PRINCIPLES.md` §14](PRINCIPLES.md#14-snapshot-plus-override-never-vendored-copies)).
 See [`docs/extending.md`](docs/extending.md) for the full extension model.
 
 A project declares only what differs from its organization; an
@@ -372,7 +372,7 @@ lists the source ids the adopter trusts and commits each pin (method + URL
 `skills/<name>/source.md` redirect (frontmatter `source:` / `organization:`
 / `skill_path:` / `evals_path:`, **not** a `SKILL.md`) names the source;
 `/magpie-setup` fetches it into the gitignored snapshot and wires it in like
-a framework skill. Per [`PRINCIPLES.md` §13](PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies)
+a framework skill. Per [`PRINCIPLES.md` §14](PRINCIPLES.md#14-snapshot-plus-override-never-vendored-copies)
 this is the one external home that *installs* rather than being merely
 referenced — pinned, verified, and adopter-vouched. See
 [`docs/skill-sources/`](docs/skill-sources/README.md).

diff --git a/PRINCIPLES.md b/PRINCIPLES.md
diff --git a/README.md b/README.md
@@ -187,7 +187,7 @@ pinned, verified source the adopter has vouched for; `/magpie-setup` fetches
 it into the gitignored snapshot and wires it in exactly like a framework
 skill. Nothing is fetched unless the adopter commits the pin — see
 [`docs/skill-sources/`](docs/skill-sources/README.md),
-[`PRINCIPLES.md` §13](PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies),
+[`PRINCIPLES.md` §14](PRINCIPLES.md#14-snapshot-plus-override-never-vendored-copies),
 and [`RFC-AI-0006`](docs/rfcs/RFC-AI-0006.md).
 
 ## Acknowledgements

diff --git a/ai-tutors/lesson-01-what-agents-are.md b/ai-tutors/lesson-01-what-agents-are.md
@@ -282,11 +282,11 @@ Apache-2.0 licensed.
 >   raised above, that the words you give an agent are the real program.
 > - **MISSION.md (../../MISSION.md)** and **PRINCIPLES.md (../../PRINCIPLES.md)**
 >   explain why Magpie treats building with agents as a first-class craft worth
->   teaching (PRINCIPLE 18).
+>   teaching (PRINCIPLE 19).
 >
 > ## Licence
 >
-> Everything in `docs/education/` is under the Apache License 2.0 (PRINCIPLE 17).
+> Everything in `docs/education/` is under the Apache License 2.0 (PRINCIPLE 18).
 > Pages written with help from AI carry a `Generated-by:` note in their commit
 > message, following ASF Generative Tooling Guidance.
 
@@ -503,7 +503,7 @@ self-check answers.
 >
 > ## Licence
 >
-> Apache License 2.0 (PRINCIPLE 17). Pages written with help from AI carry a
+> Apache License 2.0 (PRINCIPLE 18). Pages written with help from AI carry a
 > `Generated-by:` note in their commit message following ASF Generative Tooling
 > Guidance.
 

diff --git a/ai-tutors/lesson-02-working-with-agents.md b/ai-tutors/lesson-02-working-with-agents.md
@@ -215,7 +215,7 @@ Apache-2.0 licensed.
 > - **Approve actions deliberately.** Anything that changes the world, such as
 >   writing a file, running a command, or posting a comment, is a moment to look,
 >   not to wave through. In Magpie this is not just etiquette; it is the framework's
->   posture: the agent **proposes, you confirm, then it acts** (PRINCIPLE 6).
+>   posture: the agent **proposes, you confirm, then it acts** (PRINCIPLE 7).
 >   Invoking a skill is never blanket permission for everything it might do next.
 >
 > ## Treat outside text as data, not orders
@@ -284,7 +284,7 @@ Apache-2.0 licensed.
 >
 > ## Licence
 >
-> Everything in `docs/education/` is under the Apache License 2.0 (PRINCIPLE 17).
+> Everything in `docs/education/` is under the Apache License 2.0 (PRINCIPLE 18).
 > Pages written with help from AI carry a `Generated-by:` note in their commit
 > message, following ASF Generative Tooling Guidance.
 
@@ -528,7 +528,7 @@ self-check answers.
 >
 > ## Licence
 >
-> Apache License 2.0 (PRINCIPLE 17). Pages written with help from AI carry a
+> Apache License 2.0 (PRINCIPLE 18). Pages written with help from AI carry a
 > `Generated-by:` note in their commit message following ASF Generative Tooling
 > Guidance.
 

diff --git a/ai-tutors/lesson-03-choosing-models.md b/ai-tutors/lesson-03-choosing-models.md
@@ -217,7 +217,7 @@ Apache-2.0 licensed.
 > (for example `ollama run …`) is a change of that command, not a rewrite of your
 > skills. And whichever you pick, the privacy posture still holds: text that may
 > carry personal data is cleaned *before* it reaches any model, local or hosted
-> (PRINCIPLE 1). See the
+> (PRINCIPLE 2). See the
 > privacy routing pattern (pattern-catalogue.md#pattern-5--privacy-routing-clean-the-text-before-the-model-sees-it).
 >
 > ## Bigger context is not automatically better
@@ -236,7 +236,7 @@ Apache-2.0 licensed.
 > the reliable way to choose is:
 >
 > 1. Write the eval suite for your skill first (it is required anyway, per
->    PRINCIPLE 8).
+>    PRINCIPLE 9).
 > 2. Run it against two or three candidate models with `--cli`.
 > 3. Compare: which ones pass, how fast, at what cost.
 > 4. Pick the cheapest, fastest model that clears your bar, and re-check when a
@@ -260,12 +260,12 @@ Apache-2.0 licensed.
 >   can write a skill, the model choice attaches to a concrete piece of work.
 > - **Eval-driven development (eval-driven-development.md)** is how you actually
 >   compare models, including the judge model that grades prose output.
-> - **PRINCIPLES.md (../../PRINCIPLES.md)**: PRINCIPLE 1 (privacy and sandbox by
+> - **PRINCIPLES.md (../../PRINCIPLES.md)**: PRINCIPLE 2 (privacy and sandbox by
 >   default) governs what any model, local or hosted, is allowed to see.
 >
 > ## Licence
 >
-> Everything in `docs/education/` is under the Apache License 2.0 (PRINCIPLE 17).
+> Everything in `docs/education/` is under the Apache License 2.0 (PRINCIPLE 18).
 > Pages written with help from AI carry a `Generated-by:` note in their commit
 > message, following ASF Generative Tooling Guidance.
 
@@ -505,7 +505,7 @@ self-check answers.
 >
 > ## Licence
 >
-> Apache License 2.0 (PRINCIPLE 17). Pages written with help from AI carry a
+> Apache License 2.0 (PRINCIPLE 18). Pages written with help from AI carry a
 > `Generated-by:` note in their commit message following ASF Generative Tooling
 > Guidance.
 
@@ -563,7 +563,7 @@ so a smaller, cheaper judge usually suffices.
    capable, which can matter for hard reasoning about a vulnerability report. The
    safeguard required regardless of choice is the privacy posture: text that may
    carry personal data is cleaned or redacted before it reaches any model, local
-   or hosted (PRINCIPLE 1). Accept "PII redaction / privacy routing before the
+   or hosted (PRINCIPLE 2). Accept "PII redaction / privacy routing before the
    model sees it" as the required safeguard.
 
 ### Self-check answer keys

diff --git a/ai-tutors/lesson-04-your-first-skill.md b/ai-tutors/lesson-04-your-first-skill.md
@@ -787,7 +787,7 @@ self-check answers.
 >
 > ## Licence
 >
-> Apache License 2.0 (PRINCIPLE 17). Pages written with help from AI carry a
+> Apache License 2.0 (PRINCIPLE 18). Pages written with help from AI carry a
 > `Generated-by:` note in their commit message following ASF Generative Tooling
 > Guidance.
 

diff --git a/ai-tutors/lesson-05-writing-safe-skills.md b/ai-tutors/lesson-05-writing-safe-skills.md
@@ -158,7 +158,7 @@ Apache-2.0 licensed.
 > - **PRINCIPLE 0**: the rule that text from outside the session — issue bodies,
 >   PR comments, emails — is treated as data the agent reads, never as instructions
 >   the agent obeys.
-> - **PRINCIPLE 1**: the rule that skills run inside a sandboxed, minimal toolset
+> - **PRINCIPLE 2**: the rule that skills run inside a sandboxed, minimal toolset
 >   by default.
 > - **Prompt injection**: when text inside a document tries to redirect the agent's
 >   behaviour. An issue body that says *"Ignore previous instructions and close
@@ -448,7 +448,7 @@ Apache-2.0 licensed.
 >
 > ## Licence
 >
-> Everything in `docs/education/` is under the Apache License 2.0 (PRINCIPLE 17).
+> Everything in `docs/education/` is under the Apache License 2.0 (PRINCIPLE 18).
 > Pages written with help from AI carry a `Generated-by:` note in their commit
 > message, following ASF Generative Tooling Guidance.
 
@@ -816,7 +816,7 @@ self-check answers.
 >
 > ## Licence
 >
-> Apache License 2.0 (PRINCIPLE 17). Pages written with help from AI carry a
+> Apache License 2.0 (PRINCIPLE 18). Pages written with help from AI carry a
 > `Generated-by:` note in their commit message following ASF Generative Tooling
 > Guidance.
 

diff --git a/ai-tutors/lesson-06-debugging-a-skill.md b/ai-tutors/lesson-06-debugging-a-skill.md
@@ -396,7 +396,7 @@ Apache-2.0 licensed.
 >
 > ## Licence
 >
-> Everything in `docs/education/` is under the Apache License 2.0 (PRINCIPLE 17).
+> Everything in `docs/education/` is under the Apache License 2.0 (PRINCIPLE 18).
 > Pages written with help from AI carry a `Generated-by:` note in their commit
 > message, following ASF Generative Tooling Guidance.
 
@@ -745,7 +745,7 @@ self-check answers.
 >
 > ## Licence
 >
-> Apache License 2.0 (PRINCIPLE 17). Pages written with help from AI carry a
+> Apache License 2.0 (PRINCIPLE 18). Pages written with help from AI carry a
 > `Generated-by:` note in their commit message following ASF Generative Tooling
 > Guidance.
 

diff --git a/ai-tutors/lesson-07-writing-portable-skills.md b/ai-tutors/lesson-07-writing-portable-skills.md
@@ -89,8 +89,8 @@ until all five have been demonstrated by the learner, not just stated by you.
 - Teach one idea at a time. Never dump the whole lesson in one message. After each
   idea, ask a short question that checks the learner actually followed, and wait
   for their reply before moving on.
-- Keep the two axes distinct: project-agnostic (PRINCIPLE 12, no real project
-  names or hardcoded config) and model-neutral (PRINCIPLE 9, no vendor names or
+- Keep the two axes distinct: project-agnostic (PRINCIPLE 13, no real project
+  names or hardcoded config) and model-neutral (PRINCIPLE 10, no vendor names or
   harness commands) are independent. A skill can be safe but not portable, or
   portable on one axis and not the other. Do not let the learner collapse them.
 - Teach the `<upstream>` vs `<tracker>` distinction explicitly: `<upstream>` is
@@ -153,9 +153,9 @@ Apache-2.0 licensed.
 >
 > Portability has two axes:
 >
-> - **Project-agnostic** (PRINCIPLE 12): The skill works for any project that
+> - **Project-agnostic** (PRINCIPLE 13): The skill works for any project that
 >   adopts the framework, with no rewrites — only a config change.
-> - **Model-neutral** (PRINCIPLE 9): The skill works with any model backend, local
+> - **Model-neutral** (PRINCIPLE 10): The skill works with any model backend, local
 >   or hosted, current or future.
 >
 > Both axes are authoring decisions you make while you write the skill. Neither
@@ -191,9 +191,9 @@ Apache-2.0 licensed.
 > non-portable skill needs to be rewritten. That rewriting is a cost that portability
 > removes.
 >
-> PRINCIPLE 12 states the contract: *a concrete name inside a skill is a refactor
+> PRINCIPLE 13 states the contract: *a concrete name inside a skill is a refactor
 > bug, not a shortcut. Swapping projects is a config change, never a code change.*
-> PRINCIPLE 9 states the same for models: *a skill hard-coded to one vendor or model
+> PRINCIPLE 10 states the same for models: *a skill hard-coded to one vendor or model
 > family is broken, not specialised.*
 >
 > ---
@@ -361,8 +361,8 @@ Apache-2.0 licensed.
 > ```
 >
 > Changes made:
-> - `apache/kafka` → `<upstream>` (PRINCIPLE 12)
-> - "Use Claude to" → removed; the agent runs the step (PRINCIPLE 9)
+> - `apache/kafka` → `<upstream>` (PRINCIPLE 13)
+> - "Use Claude to" → removed; the agent runs the step (PRINCIPLE 10)
 > - "In Claude Code" → "Output to the conversation" (harness-neutral)
 > - The injection guard from `writing-safe-skills.md` is added
 >
@@ -412,14 +412,14 @@ Apache-2.0 licensed.
 > - **Pattern catalogue (pattern-catalogue.md)** has ready-to-copy skill shapes
 >   for common cases, each annotated with which principles it satisfies — including
 >   the placeholder convention.
-> - **PRINCIPLES.md (../../PRINCIPLES.md)**: PRINCIPLE 9 is the vendor-neutrality
->   rule; PRINCIPLE 12 is the project-agnosticism rule. Both are non-negotiable.
+> - **PRINCIPLES.md (../../PRINCIPLES.md)**: PRINCIPLE 10 is the vendor-neutrality
+>   rule; PRINCIPLE 13 is the project-agnosticism rule. Both are non-negotiable.
 >
 > ---
 >
 > ## Licence
 >
-> Everything in `docs/education/` is under the Apache License 2.0 (PRINCIPLE 17).
+> Everything in `docs/education/` is under the Apache License 2.0 (PRINCIPLE 18).
 > Pages written with help from AI carry a `Generated-by:` note in their commit
 > message, following ASF Generative Tooling Guidance.
 
@@ -636,7 +636,7 @@ self-check answers.
 >
 > The problem is a **project-specific name** — `apache/kafka` is hardcoded
 > instead of using a placeholder. This violates the project-agnostic axis
-> (PRINCIPLE 12). The step names the *issue tracker*, so the correct placeholder
+> (PRINCIPLE 13). The step names the *issue tracker*, so the correct placeholder
 > is `<tracker>`, and the corrected step is: *"Post this comment on
 > `<tracker>#NNN`."* (This mirrors the Pattern 1 example on the source page.)
 > The related placeholder `<upstream>` stands for the repository identifier
@@ -753,7 +753,7 @@ self-check answers.
 >
 > ## Licence
 >
-> Apache License 2.0 (PRINCIPLE 17). Pages written with help from AI carry a
+> Apache License 2.0 (PRINCIPLE 18). Pages written with help from AI carry a
 > `Generated-by:` note in their commit message following ASF Generative Tooling
 > Guidance.
 
@@ -762,8 +762,8 @@ self-check answers.
 **Exercise 1 - Spot the portability problems.** For each step: the non-portable
 element, the axis, and the fixing pattern.
 - Step A: `apache/kafka` in the `--repo` argument. Axis: project-agnostic
-  (PRINCIPLE 12). Fix: Pattern 1, replace with `<upstream>`.
-- Step B: "Ask GPT-4o to read the issue body". Axis: model-neutral (PRINCIPLE 9).
+  (PRINCIPLE 13). Fix: Pattern 1, replace with `<upstream>`.
+- Step B: "Ask GPT-4o to read the issue body". Axis: model-neutral (PRINCIPLE 10).
   Fix: Pattern 4, drop the vendor and just state the task ("Read the issue body and
   decide...").
 - Step C: "In Claude Code, press Ctrl+K and type /magpie-issue-triage ... output
@@ -814,7 +814,7 @@ Credit answers that (a) read the label from config, (b) replace the hardcoded
 
 **Q1. "Post this comment to the apache/kafka issue tracker."** The problem is a
 project-specific name (`apache/kafka`) hardcoded instead of a placeholder,
-violating the project-agnostic axis (PRINCIPLE 12). Corrected: "Post this comment
+violating the project-agnostic axis (PRINCIPLE 13). Corrected: "Post this comment
 on `<tracker>#NNN`." (Accept `<upstream>` if framed as the repository identifier;
 the key point is that no real repository name appears in the skill body. `<tracker>`
 is the issue tracker used in a `#NNN` reference; `<upstream>` is the `org/repo`
@@ -855,8 +855,8 @@ evidence.
 ### Summary (use at close)
 
 Portability is an authoring discipline, not a post-hoc fix. Two axes matter:
-project-agnostic (no real project names, no hardcoded config values; PRINCIPLE 12)
-and model-neutral (no vendor names, no harness commands; PRINCIPLE 9). Six patterns
+project-agnostic (no real project names, no hardcoded config values; PRINCIPLE 13)
+and model-neutral (no vendor names, no harness commands; PRINCIPLE 10). Six patterns
 cover almost every non-portable element a skill can contain: substitute
 placeholders for project names (Pattern 1), read variable values from adopter config
 (Pattern 2), run the validator before opening a pull request (Pattern 3), name

diff --git a/ai-tutors/lesson-08-eval-driven-development.md b/ai-tutors/lesson-08-eval-driven-development.md
@@ -548,7 +548,7 @@ Apache-2.0 licensed.
 >
 > ## Evals are required to release
 >
-> PRINCIPLE 8 makes evals a release requirement: a skill that ships without an
+> PRINCIPLE 9 makes evals a release requirement: a skill that ships without an
 > eval suite is not releasable, however well it does in manual testing. Every
 > Magpie release ships the eval suites alongside the skills they test.
 >
@@ -594,7 +594,7 @@ Apache-2.0 licensed.
 >   format.
 > - **`pattern-catalogue.md` (pattern-catalogue.md)** includes a "test your skill
 >   with an eval before shipping it" pattern as a ready-to-copy recipe.
-> - **PRINCIPLES.md (../../PRINCIPLES.md)**: PRINCIPLE 8 is the release rule;
+> - **PRINCIPLES.md (../../PRINCIPLES.md)**: PRINCIPLE 9 is the release rule;
 >   PRINCIPLE 0 is the data-not-instructions rule that the injection cases check.
 
 ### Lesson wrapper (exercises and self-check)
@@ -1035,7 +1035,7 @@ self-check answers.
 > <details>
 > <summary>Answer</summary>
 >
-> A skill without an eval suite is not finished (PRINCIPLE 8 and AGENTS.md
+> A skill without an eval suite is not finished (PRINCIPLE 9 and AGENTS.md
 > § Reusable skills). The PR will not pass review without the eval suite, and
 > "finish it later" means the skill is in an unverifiable state in the
 > interim — anyone who adopts it in that window has no way to check that it
@@ -1140,7 +1140,7 @@ self-check answers.
 >
 > ## Licence
 >
-> Apache License 2.0 (PRINCIPLE 17). Pages written with help from AI carry a
+> Apache License 2.0 (PRINCIPLE 18). Pages written with help from AI carry a
 > `Generated-by:` note in their commit message following ASF Generative Tooling
 > Guidance.
 
@@ -1227,7 +1227,7 @@ non-empty, but not the exact wording; they run locally with no model, so they ar
 faster and cheaper.
 
 **Q3. Write the suite in the same PR as the skill.** A skill without an eval suite is
-not finished (PRINCIPLE 8; AGENTS.md, Reusable skills). The PR will not pass review
+not finished (PRINCIPLE 9; AGENTS.md, Reusable skills). The PR will not pass review
 without it, and "finish it later" leaves the skill unverifiable in the interim, so any
 adopter in that window cannot check it works. The harness runs in print mode with no
 credentials, so writing cases needs no live model.