@rubytech/create-maxy-code 0.1.0

package/payload/platform/plugins/admin/skills/plainly/references/worked-examples.md

@@ -0,0 +1,301 @@
+# /plainly worked examples
+
+Twelve examples that demonstrate the rules in SKILL.md against concrete cases. Each example shows: a source, a polished version, and the failure modes the polish avoids.
+
+**Note on em-dashes in this file.** The current rule (see SKILL.md "AI tells to strip") prohibits em-dashes anywhere in polished output. Examples 1 to 11 below were written before that rule reached its no-exception form; their polished versions therefore still contain em-dashes that, by today's rule, should be commas, semicolons, parentheses, or two sentences. The bad-pattern quoted illustrations (under "Source", "First-pass", "Failed version") keep their em-dashes intentionally, since they are showing what to avoid. Example 12 is the canonical reference for the no-em-dash standard.
+
+**Note on identifying material.** Examples are presented in generic form. Where an earlier draft referenced a specific codebase, writer, or pitch, the reference has been replaced with neutral phrasing (e.g. "the reference codebase" instead of a project name).
+
+---
+
+## Worked example: integration
+
+> **User:** what is integration, in plain English?
+
+> Integration is the act of adding up all the infinitesimal changes specified by a differential equation over an interval, giving the system's state at the end of that interval. If each change is random, that end state is a distribution of possible values; if each change is deterministic, it is a single value.
+
+**Failure modes this avoids, recorded as anti-patterns:**
+
+- *"...combines all the discrete steps..."*: "discrete" is wrong (the limit is continuous); "steps" connotes uniform sub-intervals.
+- *"...the act of stitching all the infinitesimal slices..."*: "stitching" is a sewing metaphor for *adding up*; "slices" is a metaphor for *changes*.
+- *"...specified by a rule..."*: "rule" is a vague placeholder for *differential equation*.
+- *"...if each increment is random (an SDE) ... deterministic (an ODE)..."*: "increment" connotes positive (changes can flip sign); the parenthetical acronyms are jargon redundant with the surrounding "random" / "deterministic" clauses.
+
+Each failure leaks a term that would itself need explanation. The polished version contains none.
+
+---
+
+## Second worked example: a richer concept demands the full template
+
+> **User:** /plainly "S_T is lognormal"
+
+> "S_T is lognormal" means the logarithm of S_T (denoted log(S_T)) is normally distributed. This means S_T itself is always positive and large upward moves are more likely than relative downward moves. Visually, the distribution is skewed to the right, with a long right tail. This property is exactly why Black-Scholes is closed-form (can be solved analytically rather than numerically).
+
+**Failure modes this avoids, recorded as anti-patterns:**
+
+- *"'S_T is lognormal' means the logarithm of S_T follows a normal (bell-curve) distribution."*: definition only. Has the precise terms but no scaffolding (no implications, no visual, no significance). The reader gets the dictionary entry but cannot use it.
+- *"'S_T is lognormal' describes how its possible values are spread: always above zero, with most outcomes clustered near a central level, larger upward moves possible, and no values below zero."*: over-correction the other way. Avoids the technical terms ("logarithm", "normally distributed") that the doc actually uses elsewhere, and so leaves the reader with no anchor between this paragraph and the rest of the document. Plain English doesn't mean throwing out vocabulary the doc has already established.
+
+The polished version uses the precise terms, denotes the symbol explicitly, *and* scaffolds with implications, visual, and significance. Each element does independent communicative work.
+
+---
+
+## Third worked example: function-signature notation is still a formula
+
+> **User:** why is the Merton model a one-dimensional pricing equation when its jumps are random?
+
+> The dimensionality of a pricing equation counts state variables, not sources of randomness. The equation solves for the option's value as one function across every possible spot price and every time before expiry; it does not enumerate possible futures, it averages over them. With Merton jumps, the only state variable is spot price, so the equation is one-dimensional in space. With Heston stochastic variance, variance is itself a process that evolves through time and feeds back into the spot price's dynamics, so it has to be tracked alongside spot: two state variables, two spatial dimensions.
+
+**Failure modes this avoids, recorded as anti-patterns:**
+
+- *"...the option's value `V(S, t)` as a single function over the state space..."*: `V(S, t)` is function-signature notation, which fails the read-aloud test. Nobody says "V of S comma t" in conversation. Express it in words: "the option's value as a function of spot price and time".
+- *"...State = (S). Two-dimensional state: (S, v)..."*: tuple notation is a formula. Say "the only state variable is spot price" and "the state is now spot price and variance".
+- *"...regime index k ∈ {1..K}..."*: set-builder notation is a formula. Say "regime index running from one to K" or just "the regime label".
+
+The general principle: any expression that uses parentheses, commas, or symbols to encode a relationship, not just equations with equals signs, is a formula and breaks the spoken register. Plain English forces you to *unpack* the relationship into its English statement, which is also where the understanding lives.
+
+---
+
+## Fourth worked example: density beats scaffolding when the user has framed the question
+
+> **User (paraphrased framing, ~70 words):** "The integral term in a pricing equation is the line 'average the option's value across all possible post-jump spot levels'. Doing that average with infinite precision is impossible, you can't actually visit every possible jump size. So we approximate the integral as a *weighted average over a small handful of carefully chosen sample points*. That approximation is called **quadrature**." Refine.
+
+> Polished response (~60 words): "Quadrature approximates an integral as a weighted sum over sample points whose locations and weights are chosen so the sum is exact for a stated family of functions, usually polynomials up to some degree against a fixed weight. Seven-node Gauss-Hermite (the reference rule) is exact for degree-thirteen polynomials against a normal density, fitting the lognormal jump distribution closely enough that seven evaluations replace hundreds of naive rectangles."
+
+**Failure modes this avoids, recorded as anti-patterns:**
+
+- *Re-establishing what the framing established.* Restating "the approximation of an integral as a weighted sum over sample points" when the framing already said exactly that. Filler dressed as definition.
+- *Re-doing the visual when the framing already gave one.* The framing's "average across post-jump spot levels" is a working picture. Adding "imagine rectangles under a curve" describes the same thing in different words and adds zero precision.
+- *Re-motivating the problem.* The framing already explained why we need the approximation ("can't visit every jump size"). Re-explaining the motivation is wasted words.
+- *Adjacent context dressed as significance.* "Per-iteration cost rises ~7×" is true and interesting but does not deepen understanding of *what quadrature is*; it answers a different question. Save it for a follow-up if asked.
+
+The precision delta is the answer's only real content. Here, the delta over the framing is: *what "carefully chosen" actually means* (locations and weights making the sum exact for a stated function family), and *which specific rule the reference codebase uses* and *why that rule fits this case*. Everything else is scaffolding the user does not need.
+
+The general principle: a longer answer to a well-framed question is a worse answer *when the framing is already audience-appropriate*. If the framing is researcher shorthand and the audience is new to the topic, see the fifth example.
+
+---
+
+## Fifth worked example: precision without bridging fails the new-to-topic test
+
+The terse refinement from the fourth example is precise and shorter than the framing, but it lands only for a reader who already owns the specialist vocabulary, which is not the /plainly audience. The new reader does not know what "exact for a stated family of functions" implies, why polynomial-exactness translates to near-exactness on smooth functions, what "against a fixed weight" operationally means, or how the lognormal jump distribution connects to a normal-density quadrature rule. Each of those gaps has to be bridged inside the explanation.
+
+Polished response (~180 words, walks the new reader through):
+
+> Quadrature is a way of computing an integral by evaluating the function at a small number of sample points, multiplying each value by a weight, and adding them up. The trick is choosing the points and weights so that the sum is *exactly right* for an entire class of functions at once, typically all polynomials up to some chosen degree.
+>
+> That promise is the source of the leverage. If the function you actually want to integrate happens to be one of those polynomials, the sum is the true answer, not an approximation. For functions that are close to one (which most smooth functions are), the error is tiny. So instead of needing hundreds of evenly-spaced samples, a handful placed where they extract the most information about the function's shape gives the same accuracy.
+>
+> The reference codebase uses a rule called Gauss-Hermite with seven samples. It is exact for any polynomial of degree thirteen *multiplied by a bell curve* (a normal density). That last detail matters: Gauss-Hermite is built specifically for averages over normally-distributed quantities. The lognormal jump distribution in the model is exactly that (a quantity whose logarithm is normal), so once the integral is rewritten in log-space, the rule fits the integrand almost perfectly. That is why seven evaluations replace what would otherwise need hundreds.
+
+**Failure modes this avoids, recorded as anti-patterns:**
+
+- *"Exact for a stated family of functions" without saying what that means or why it matters.* A new reader does not know that exactness on a function family implies near-exactness on functions close to that family. Spell it out: the sum is exactly right for the named class, and close to right for things close to the class.
+- *"Polynomials against a fixed weight" without unpacking the phrase.* "Against a weight" sounds like it has a precise meaning to the writer, but reads as decorative noise to a new reader. Either say "polynomials multiplied by a fixed function (a weight)" once and operationally, or skip the abstract framing and go to the concrete case.
+- *"Fitting the lognormal jump distribution closely enough"*: fitting *how*? The new reader has to take this on faith. Bridge it: lognormal means the *logarithm* of the quantity is normal; Gauss-Hermite is built for normal-weighted integrals; rewrite the integral in log-space and the rule and integrand match.
+- *Skipping the operational definition of the technique itself.* Saying "approximates an integral as a weighted sum over sample points" assumes the reader can picture what that means in code or on paper. Walk them through: pick points, evaluate, multiply by weights, add. One sentence, but load-bearing.
+
+The general principle: **density is only a virtue when every dense phrase lands.** A short answer that uses three specialist phrases is *longer* in reading time than a longer answer that uses none, because the reader has to look each one up. If you find yourself using a phrase that compresses several specialist concepts ("exact for a polynomial family"), either unpack the compression inside the explanation or expect the answer to fail the new-to-topic test.
+
+---
+
+## Sixth worked example: scope-matching, the operational definition is often enough
+
+The fifth example bridges all the way to the named rule and its mechanism. That depth is correct only when the reader will *use* the mechanism: selecting node counts, comparing rules, verifying near-exactness claims. When the reader will use the technique as a black box (the case in a risk-analysis writeup, where quadrature appears once as "the method we use to compute the jump integral"), the operational definition alone is enough.
+
+The writer's polished version (~45 words, in-document phrasing):
+
+> Calculating the integral term in the PIDE, the average of the option's value across all possible post-jump spot levels, is actually not possible. Instead, we approximate the integral as a *weighted average over a small number of carefully chosen sample points*, a method known as **quadrature**.
+
+Two prose-level moves worth recording, both of which trimmed the version above from a slightly wordier earlier draft:
+
+- *"i.e. infinite precision is impossible"* to *"is actually not possible"*: drops the technical-feeling "i.e." and uses a parenthetical that reads more naturally aloud. The missing word "exactly" is recovered by the reader from the contrast with "approximate" in the next sentence; spelling it out would be filler.
+- *"an approximation method"* to *"a method"*: once "approximate the integral as ... a method" is on the page, the word "approximation" is already implied. Repeating it is one of the most common forms of filler in technical writing: the over-specified noun phrase that names the role its sentence already established.
+
+This passes all three tests for its audience:
+
+- *Aloud test:* yes, reads cleanly without notation.
+- *Understanding test:* yes, the reader knows operationally what quadrature does (sample, weight, average), which is the level at which they will use it.
+- *New-to-topic test:* yes, every phrase is plain. "Carefully chosen" is left as a black-box modifier, not unpacked into polynomial-exactness; that is correct, because the reader does not need to choose the points or verify the rule. Trusting "carefully chosen" is part of the black-box contract.
+
+**Failure modes this avoids, recorded as anti-patterns:**
+
+- *Over-engineering past the question's scope.* If the surrounding doc only requires the reader to know what quadrature *is*, explaining *how* Gauss-Hermite achieves exactness is filler, even when every phrase is plain English. The fifth-example bridging answer is wrong for the sixth-example reader.
+- *Mistaking "how the technique works" for "what the technique is".* These are different questions. A /plainly definition answers the second by default. Mechanism is a follow-up question and warrants its own explanation only when asked.
+- *Treating richer-when-possible as a virtue.* The four-item template (definition, consequences, visual, significance) maxes out at four for a reason. If the reader's use of the concept does not depend on consequences, visual, or significance, the definition alone suffices, and adding the others is padding.
+- *Refusing to leave a hand-wavy modifier hand-wavy.* Phrases like "carefully chosen" are sometimes load-bearing precisely because they signal *trust the technique without explaining it*. A risk-analysis reader does not need to know what makes the choice careful; they need to know that someone competent made it.
+
+The general principle: **what the reader needs to DO with the concept dictates the depth, not the concept's intrinsic richness.** Quadrature is intrinsically rich, but a risk-analysis reader uses it as a black box ("samples and weights chosen carefully") and that level of depth is the right answer. The fifth example and the sixth example are both correct plain English, for different readers. The /plainly invocation should default to the operational scope (sixth) and reach for mechanism (fifth) only when the reader will need mechanism.
+
+---
+
+## Seventh worked example: when the source is one jargon-packed sentence, the plain-English answer is also one sentence
+
+Sometimes the user pastes a single sentence, often a sentence dense with specialist vocabulary, and asks for plain English. The temptation is to unpack each piece of jargon into its own paragraph, define the surrounding context, walk through implications, add a "catch" or a payoff. That produces a wall of text masquerading as plain English. The right answer is a **transliteration**: keep the source's syntactic frame, swap each jargon term for its plain-English equivalent, stop.
+
+> **User:** /plainly "parameter standard errors fall out of the calibrated Jacobian via the usual covariance formula."
+
+> Polished response (one sentence): "Since the calibration produces a table of sensitivities as part of its loss-minimisation process, this table is converted to statistics that express the margin of error in the parameters."
+
+The mapping is direct:
+
+- "parameter standard errors" becomes "the margin of error in the parameters"
+- "fall out of" is preserved by phrasing the conversion as a follow-on to a process that was happening anyway ("since the calibration produces … as part of its loss-minimisation process")
+- "the calibrated Jacobian" becomes "a table of sensitivities"
+- "via the usual covariance formula" becomes "is converted to statistics that …"
+
+Each jargon term lands in the same syntactic slot it occupied in the source. Nothing is added; nothing is cut. The result is one sentence, mirroring the source's one sentence.
+
+**Failure modes this avoids, recorded as anti-patterns:**
+
+- *Adding numeric examples to convey what "margin of error" means.* The reader knows what a margin of error is. Adding "an 18% volatility give-or-take 0.5% is very different from 18% give-or-take 8%" is filler that explains a concept the reader did not ask about.
+- *Explaining surrounding context that wasn't in the asked sentence.* The χ²-weighting connection (which is what makes the formula statistically meaningful) appears in *adjacent* sentences in the source document, not in the phrase being asked about. Bringing it in is scope creep: answer the sentence that was asked, not a richer one nearby.
+- *Re-stating the "for free" payoff multiple times.* "Comes for free", "no extra rounds of fitting", "no simulation needed" all say the same thing. One mention is enough; multiple is filler dressed as emphasis.
+- *Adding a "the catch" or "the payoff" paragraph for nuance.* The source phrase contains no catch. Adding one expands the explanation beyond the asked scope.
+- *Walking the reader through worked motivation ("imagine you have a calibration that just finished…").* The source is a present-tense statement of fact. The plain version should be too. Story-mode framing is filler.
+
+The general principle: **transliterate, don't expand.** When the source is a single sentence dense with jargon, the plain-English version should preserve the source's sentence structure and only replace each jargon term with its plain-English equivalent. The reader is not asking "teach me everything about parameter uncertainty estimation in nonlinear least squares"; they are asking "what does *this sentence* mean". Match the scope of the question, not the depth of the underlying topic. The verbal-conversation test is sharpest here: if you would say one sentence to a colleague who asked "what does that mean?", write one sentence. Anything more is the writer's anxiety, not the reader's need.
+
+---
+
+## Eighth worked example: symbol anchoring done right (transliteration, second instance)
+
+The seventh example established the transliterate-don't-expand rule. The eighth shows the same rule applied cleanly with **symbol anchoring**: when the source uses bare symbols as jargon (e.g. "V₀ memory"), the plain version puts the *meaning* in front and the *symbol* in parentheses as a cross-reference back to the surrounding document.
+
+> **User:** /plainly "The V₀ memory has decayed to θ by the time of any VX-future expiry, so the V₀ term drops out."
+
+> Polished response (one sentence): "By the time any VX future expires, the variance has mean-reverted from its starting value (V₀) to its long-run level (θ), so the formula no longer depends on V₀."
+
+The mapping is, again, direct:
+
+- "V₀ memory" becomes "starting value (V₀)": meaning first, symbol as parenthetical cross-reference.
+- "has decayed to θ" becomes "has mean-reverted to its long-run level (θ)": same anchoring move, same syntactic slot.
+- "by the time of any VX-future expiry" becomes "by the time any VX future expires": light prose tweak, same content.
+- "the V₀ term drops out" becomes "the formula no longer depends on V₀": operational restatement.
+
+**Why this works:**
+
+- *Symbol anchoring preserves cross-referenceability without leading with jargon.* A reader who knows the doc recognises V₀ and θ as the variables from the previous bullet's formula; a reader new to the topic gets the meaning from "starting value" and "long-run level" without needing to recognise the symbols. Both audiences are served by one sentence.
+- *No anti-patterns from the seventh example were committed.* No numeric example explaining what mean-reversion is. No re-derivation of the formula. No "the catch is …" or "the payoff is …" closer. No story-mode preamble.
+
+**Failure modes this avoids, recorded as anti-patterns:**
+
+- *Defining V₀ from scratch.* "V₀ refers to the initial value of the variance process at the moment a regime starts; over time, this initial-value memory exponentially decays toward the long-run level …": too long. The doc has already introduced V₀ in the previous bullet's formula. Anchoring it parenthetically (V₀) is enough.
+- *Bringing in adjacent variables not in the asked sentence.* "V₀ is the initial variance, θ is the long-run mean, the variance mean-reverts at rate κ towards θ …": κ does not appear in the asked sentence. Including it is scope creep.
+- *Adding editorial commentary.* "This is why we can simplify the formula at long horizons …": the source makes a factual statement, not an editorial one. The plain version should match.
+- *Re-deriving the source's claim instead of stating it.* Listing the formula again with V₀ replaced by θ to "show" what dropping out means. The reader did not ask for the derivation.
+
+The general principle reinforces the seventh example: **one sentence in, one sentence out.** Symbol anchoring (meaning first, symbol parenthetical) is the standard move when the source uses bare symbols; it keeps the plain version cross-referenceable to the surrounding doc without leading with jargon.
+
+---
+
+## Ninth worked example: Greek letters are jargon, parenthetical clarifications must add substance, watch the register
+
+The eighth example introduced symbol anchoring. The ninth shows three failure modes that are easy to commit on a first attempt even when the principle is known: (1) using a Greek letter as the primary referent rather than as a parenthetical anchor, (2) keeping a self-referential clarification that introduces more jargon than it removes, and (3) reaching for a casual-register word that doesn't match the document.
+
+> **User:** /plainly "**VIX options**: lognormal-mixture in IV space with vol-of-VIX `η_i = ν_i / (2·√θ_i)` (heuristic from sqrt-derivative chain rule on Heston dynamics). Same closure as the constant-σ path; the only difference is where η comes from."
+
+> Polished response: "**VIX options**: priced as a mixture of lognormal distributions of implied volatility, one per regime, with each regime's vol-of-VIX (η_i) derived from the Heston parameters as vol-of-vol divided by twice the square root of long-run variance. The pricing method is otherwise the same as in the constant-volatility model; only the source of vol-of-VIX changes: fitted directly per regime under constant-volatility, derived from the Heston parameters here."
+
+The mapping:
+
+- "lognormal-mixture in IV space" becomes "a mixture of lognormal distributions of implied volatility": unpacks "IV space" into its plain meaning.
+- "vol-of-VIX η_i = ν_i / (2·√θ_i)" becomes "vol-of-VIX (η_i) derived from the Heston parameters as vol-of-vol divided by twice the square root of long-run variance": meaning leads, symbol anchors parenthetically; the formula is described in words.
+- "(heuristic from sqrt-derivative chain rule on Heston dynamics)" is **dropped**. The clarification's content ("approximate") is recoverable from broader doc context; its form introduces "chain-rule" which is itself jargon.
+- "Same closure as the constant-σ path" becomes "The pricing method is otherwise the same as in the constant-volatility model": *closure* to *method* (register), *constant-σ* to *constant-volatility* (Greek-letter rule).
+- "the only difference is where η comes from" becomes "only the source of vol-of-VIX changes: …": the plain-English term is used throughout, *including* in the back-reference. Anchoring (η_i) once is for cross-reference to the surrounding doc, not a licence to use η as a back-reference later in the same paragraph; the second use would still be jargon to a reader who can't decode the letter.
+
+**Failure modes this avoids, recorded as anti-patterns:**
+
+- *Using a Greek letter as the primary referent.* The source's "vol-of-VIX η_i" treats η_i as the named-entity, with "vol-of-VIX" as the descriptor. A reader who doesn't recognise η is stuck; they don't even know what Greek letter it is, let alone what it represents. The plain version inverts the order: vol-of-VIX is the entity, (η_i) is the parenthetical anchor for cross-reference.
+- *Back-referencing the symbol after anchoring it once.* "Only the source of η changes" assumes the reader can map η back to the parenthetical anchor a sentence ago. That mapping is itself the cognitive cost the parenthetical was meant to remove. Use the plain-English term throughout (*"only the source of vol-of-VIX changes"*); reserve the symbol's appearances to (1) a single anchored introduction for cross-reference and (2) any place where the symbol genuinely appears in a formula the reader might look up.
+- *Keeping a self-referential clarification that adds more jargon than it removes.* "(a chain-rule shortcut on the Heston dynamics)" looks like it's helping the reader but introduces "chain-rule", a term the reader may not own. If the clarification needs its own clarification, drop it. The point that the formula is approximate can be inferred from the surrounding text (the broader Heston pricing section already mentions closed-form approximations) and does not need to be spelled out at every formula.
+- *Reaching for a casual-register word like "recipe" (or "trick", "vibe", "bake in").* These words carry tone from cooking and conversational registers and read as glib in technical writing. *Method*, *technique*, *approach* are the register-neutral equivalents.
+- *Greek-letter compactness as a false economy.* "Constant-σ model" is no shorter than "constant-volatility model" once you account for σ being unrecognisable to part of the audience. Save the Greek symbol for the back-reference; lead with the word.
+
+The general principle: **the recursive rule is more demanding than it looks.** A plain-English explanation cannot contain terms that need their own explanation, and that includes Greek letters used as primary referents (which require recognising the alphabet) and parenthetical clarifications that introduce new jargon. Every symbol in the source is a candidate for being downgraded to a parenthetical anchor; every parenthetical clarification in the source is a candidate for being dropped if its plain version would itself need clarifying.
+
+---
+
+## Tenth worked example: "same as X" references must define X, not punt to it
+
+Sometimes a source phrase says "X works the same as Y, except for Z". The temptation is to mirror that structure in the plain version: "X works the same as Y, except Z." But this assumes the reader already knows what Y is, and usually they don't, which is why they invoked /plainly. The plain version must **describe** Y inline, not refer to it. Otherwise the explanation is recursive: it defers the work to a definition the reader doesn't have.
+
+> **Source (continuation of the ninth example):** "...Same closure as the constant-σ path; the only difference is where η comes from."
+
+> **Failed plain version:** "...The pricing method is otherwise the same as in the constant-volatility model; only the source of vol-of-VIX changes: fitted directly per regime under constant-volatility, derived from the Heston parameters here."
+
+> **Fixed plain version:** "...The pricing method is otherwise the same as in the constant-volatility model, i.e. each regime contributes one Black-76 lognormal price using the regime's VIX as forward and vol-of-VIX as volatility input, weighted by the regime's occupancy probability at expiry, then discounted to today."
+
+What changed: the failed version *repeated* a structural claim already made in sentence 1 ("the only difference is the source of vol-of-VIX") without ever describing what the constant-volatility pricing method actually does. The fixed version uses the second sentence to **spell out** the method, so the reader doesn't need to look elsewhere.
+
+**Failure modes this avoids, recorded as anti-patterns:**
+
+- *Punting on the "same as X" reference.* "Same as the constant-volatility model" is meaningful only if the reader already knows that model. If the doc doesn't define it nearby (and often it doesn't, in plain-English passages), the plain version must define it inline. Anything else is the writer pointing at the answer instead of giving it.
+- *Repeating a structural claim instead of substituting content.* "Same except for Y" is a *structural* statement; it tells you the shape of the comparison, not the substance. If sentence 1 already established Y, then sentence 2's only remaining job is to describe X. Repeating "the only difference is Y" is filler that pretends to be content.
+- *Trusting the surrounding doc to do the work.* The reader of a /plainly explanation may not have read (or remembered) the surrounding section that defines X. The plain version should be self-contained at the bullet/sentence level. If a definition is needed, inline it.
+
+The general principle: **plain English must contain the content the reader needs, not point to it.** A "same as X except Y" construction qualifies as plain English only if X is defined nearby in language the reader already has. If X is itself a piece of doc-internal vocabulary, replace the reference with the definition. The shorthand of "same as X" is a writer's economy, not a reader's, and plain English exists for the reader.
+
+---
+
+## Eleventh worked example: when in doubt, go simpler, the audience is less experienced than the writer thinks
+
+The seventh-through-tenth examples established transliteration discipline for jargon-dense single sentences. The eleventh adds a meta-principle: when the writer thinks "this audience can handle 'Fourier methods' / 'characteristic function' / 'integrated variance distribution'", the writer is overestimating. The /plainly audience is genuinely new to the topic. Specialist proper nouns ("Fourier", "Carr-Madan"), placeholder nouns ("methods", "techniques"), stacked-modifier noun phrases ("integrated CIR variance distribution"), and elaborate phrasings for plain claims ("match shape to negligible practical error") should all default to their plainer equivalents. The cost of going one level too plain is mild (an experienced reader feels patronised); the cost of going one level too jargon-heavy is severe (the new reader bounces off entirely). The asymmetry favours plainer.
+
+> **Source:** "Exact VIX pricing under Heston would require Fourier methods on the integrated CIR variance distribution; the closed-form approximations match shape to negligible practical error and are fast enough for repeated pricing."
+
+> **First-pass plain version (still too jargon-heavy):** "Exact VIX pricing under Heston would require Fourier methods applied to the distribution of integrated variance; the closed-form approximations used here match the exact shape to negligible practical error and are fast enough to call repeatedly."
+
+> **Polished plain version:** "Exact VIX pricing under Heston would require a transformation of the variance probability distribution but the closed-form approximations we use here instead are close enough in terms of residual error and fast enough that we can call them repeatedly."
+
+The second-pass mapping (first-pass to polished):
+
+- "Fourier methods" becomes "a transformation": drops the proper noun (*Fourier*); drops the placeholder noun (*methods*); names the actual operation.
+- "applied to the distribution of integrated variance" becomes "of the variance probability distribution": unstacks the modifier chain (drops *integrated* as a load-bearing concept the reader doesn't need at this scope).
+- "match the exact shape to negligible practical error" becomes "are close enough in terms of residual error": collapses the elaborate phrasing into the basic claim (*close enough*).
+- "fast enough to call repeatedly" becomes "fast enough that we can call them repeatedly": slightly more conversational.
+- *Added* "but" / "we use here instead": makes the contrast structure explicit so the reader doesn't have to construct it.
+
+Two observations worth recording:
+
+- **Plainness is not shortness.** The first-pass version was 36 words; the polished is 39. The polishing did not compress, it *substituted vocabulary*. Each technical word was downgraded one or two levels of specialism without changing the sentence's length or shape.
+- **The first pass felt plain to the writer because the writer is comfortable with "Fourier methods" and "integrated variance distribution".** That comfort is precisely the problem: the writer's audience-model is calibrated to the writer's own background, not to the new reader's. The fix is a deliberate downward bias on every borderline word.
+
+**Failure modes this avoids, recorded as anti-patterns:**
+
+- *Treating proper nouns as low-cost vocabulary.* "Fourier methods", "Carr-Madan", "Heston-style", "Black-76". The proper noun names a person or paper; the reader does not need to know who Fourier was to understand a transformation. Drop the proper noun and name the operation. Keep it only where it's genuinely load-bearing as a citation.
+- *Using placeholder nouns ("methods", "techniques", "approaches") where the operation can be named.* "Fourier methods" becomes "a transformation". "An approximation method" becomes "an approximation". "A numerical technique" becomes the named technique if you can. The category-name is rarely the level of abstraction the reader actually needs.
+- *Keeping stacked-modifier noun phrases intact.* "Integrated CIR variance distribution" stacks three modifiers on one noun. A new-to-topic reader cannot parse this in sequence. Unstack into a phrase: "the variance probability distribution", "the distribution of variance over time". Each modifier you keep must earn its place.
+- *Elaborate verb-noun phrasing for claims that "close enough" expresses plainly.* "Match shape to negligible practical error", "preserve fidelity within tolerance", "exhibit convergence under the metric": these are fancy ways of saying "are close enough", "match closely", "converge". When the elaborate phrasing doesn't add precision the reader needs at that scope, downgrade.
+- *Leaving the reader to infer rhetorical relationships from punctuation.* The source's semicolon hides an implicit "but"; the second clause is offered *instead of* the first. Plain English makes the contrast explicit with the connective word ("but", "though", "instead").
+- *Calibrating the audience model to the writer's own background.* If "Fourier" feels obvious, that's evidence it should be dropped, not kept. The writer is the wrong baseline. The new reader is a baseline two or three levels below the writer's intuition.
+
+The general principle: **default to plainer than you think necessary; restore precision only when it would otherwise be lost.** Three or four passes through a /plainly answer is normal, and each pass surfaces one more layer of vocabulary the writer was unconsciously treating as plain. The precision-pass at the end of the skill's "Rules" section is not a single check; it is an iterated downward search for the level at which every word lands for the genuinely new reader.
+
+---
+
+## Twelfth worked example: format scaffolding is itself the AI tell
+
+The first eleven examples were about word-level and sentence-level AI tells. The twelfth covers a higher-order failure: when the source presents itself in the heading-and-bullet format AI defaults to in marketing copy, the polish must question the format itself, not just refine the prose inside it. Bold-tag headings followed by em-dash separators followed by stacked one-liners read as AI marketing-page output even when every individual word is plain.
+
+> **Source:** A consultancy pitch presenting three offerings as `**Bold Heading** — description` blocks, preceded by a signpost line introducing them as a numbered set ("Three ways I work with clients:"), and closed with a tricolon of three short parallel-shape sentences in the form "I [verb] the [noun]."
+
+> **Failed polish (kept the format intact):** Same headings, same em-dash separators between heading and description, closing tricolon collapsed to one sentence with three verbs. Word-level AI tells were caught; format-level ones were not. The result still reads as AI marketing copy because the visual scaffold is preserved.
+
+> **Gold-standard polish (prose):** Three offerings folded into running prose, each introduced by a verb the writer would actually say in conversation. No bold headings. No em-dashes (the separator becomes a comma or hyphen-with-spaces if needed). The signpost line is deleted. The closing tricolon is removed entirely, not collapsed. Any closing rhetorical sequence becomes a single conditional invitation to the reader, on the pattern "If you have recognised X and understand Y, then I can help you put Z into practice."
+
+**Failure modes this avoids, recorded as anti-patterns:**
+
+- *Treating heading-and-em-dash format as a feature of the source rather than a constraint to question.* In marketing copy aimed at human readers, prose almost always does the same job better. The heading-and-bullet format itself signals "AI marketing page", regardless of the words inside it.
+- *Collapsing a rhetorical tricolon instead of removing it.* The previous example showed the tricolon could be merged into one sentence to satisfy the cadence rule. The gold standard goes further: if a rhetorical close adds no new content, just strong-form repetition, remove it. The reader has read the offerings and does not need a chant of the verbs.
+- *Preserving signposting prose (e.g. "Three ways I work with clients:") after removing the headings it signposted.* Once the format is prose, the signpost is double-bookkeeping.
+- *Keeping em-dashes in the polish even after the rule was already in the catalogue.* This is the writer's instinct for "the strong-break exception" overriding the discipline. The exception has now been removed; the rule is: never an em-dash.
+- *Treating a specific-sounding number as load-bearing precision when the writer cannot actually source it.* Specific numbers ("a 1-2 year head start", "30% faster", "10x cheaper") read as authoritative, but if the writer cannot defend the bound, a plain qualifier ("a limited head start", "noticeably faster", "much cheaper") expresses the same shape without false confidence.
+- *Inserting structure that creates work for the reader without creating value.* Bold headings make the page scannable but force the reader to integrate three separate sections instead of following one flow. For three short offerings, prose with conversational lead-verbs reads faster than a heading-bulleted list.
+
+The general principle: **the AI-tells catalogue applies to format as much as to vocabulary.** Bold headings followed by em-dash separators followed by parallel one-liners is the visual signature of AI marketing-page output. When the source is in that format, the precision pass must ask whether prose would do the same job, and in human-facing copy the answer is almost always yes.
+
+Two meta-observations from this case worth recording:
+
+- **Lenience after a partial fix is the dominant failure mode.** The polish caught most word-level tells, then declared victory. The format itself was an unaudited surface. A strict pass requires asking, at every level (word, sentence, paragraph, format), whether the source's choice was the writer's or AI's default.
+- **Specific carve-outs in the rules become loopholes.** The "strong break" exception for em-dashes was the failure point: the writer's instinct rationalised every em-dash as a strong break. Rules with no exceptions are easier to honor than rules with one defensible exception, because the defensible exception swallows the rule.

package/payload/platform/plugins/admin/skills/plugin-management/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: plugin-management
+description: "Install, remove, enable, and configure plugins and account settings via conversation."
+---
+
+# Plugin Management
+
+Manage plugins and account settings at any time via conversation.
+
+## Claude Official Plugins
+
+External Claude Code plugins (Stripe, Playground):
+
+- Install: `claude plugin install <name>@claude-plugins-official`
+- Remove: `claude plugin uninstall <name>@claude-plugins-official`
+- List installed: `claude plugin list`
+- List available: `claude plugin marketplace list`
+
+## Claude Anthropic Verticals
+
+Three optional plugins from Anthropic's vertical marketplaces, registered by the installer alongside `claude-plugins-official`. None are auto-installed; the user picks each deliberately during onboarding or by name later.
+
+| Plugin | Marketplace | Install | Caveat |
+|--------|-------------|---------|--------|
+| `kyc-screener` | `claude-for-financial-services` | `claude plugin install kyc-screener@claude-for-financial-services` | Outputs are draft work product for human review. UK estate agents under MLR 2017 are AML-regulated; compliance specialist owns sign-off. |
+| `meeting-prep-agent` | `claude-for-financial-services` | `claude plugin install meeting-prep-agent@claude-for-financial-services` | Overlaps with the business-assistant calendar-prep flow with FSI-flavoured templates — pick one path deliberately. |
+| `pdf-viewer` | `knowledge-work-plugins` | `claude plugin install pdf-viewer@knowledge-work-plugins` | Interactive in-app viewer (v0.2.0). Click-through replaces conversation for this surface — different integration shape from the chat-driven skills. |
+
+Removal mirrors install: `claude plugin uninstall <name>@<marketplace>`.
+
+## {{productName}} Plugins
+
+Built-in plugins under `$PLATFORM_ROOT/plugins/`:
+
+- Enable: call `plugin-toggle-enabled` with `pluginName` and `action: "enable"`. Activates the plugin's behaviour embed and MCP server from the next session. Plugins with scheduled behaviour (declared via `lifecycle` in PLUGIN.md frontmatter) are activated automatically by the platform heartbeat within one minute — no separate setup command needed.
+- Disable: call `plugin-toggle-enabled` with `pluginName` and `action: "disable"`. Deactivates from the next session. Any scheduled Events owned by the plugin (`sourcePlugin` field) are cancelled automatically by the platform heartbeat.
+- The tool refuses core plugins (admin, memory, docs, cloudflare, anthropic) and refuses plugins not installed under `$PLATFORM_ROOT/plugins/`. Direct `Edit` of `account.json` is denied by the pre-tool-use hook — `plugin-toggle-enabled` is the only legitimate path.
+
+## Premium Plugins
+
+Premium plugins are purchased separately and delivered from a staging area to the active plugin directory. Two MCP tools handle all premium plugin operations deterministically — no filesystem commands are delegated to the agent.
+
+### Browsing available premium plugins
+
+Call `premium-list`. It returns structured data for every plugin in the staging area: name, type (standalone/bundle), description, purchase status, and delivery status (per sub-plugin for bundles). Present the results using `render-component` with the `card` type.
+
+### Plugin info before purchase
+
+When the user asks about a specific premium plugin (e.g., "tell me about the teaching plugin"), check the staging directory for both `PLUGIN.md` (standalone) and `BUNDLE.md` (bundle). For standalone plugins, read `$PLATFORM_ROOT/../premium-plugins/{name}/PLUGIN.md`. For bundles, read `$PLATFORM_ROOT/../premium-plugins/{name}/BUNDLE.md` and present the bundle description, sub-plugin breakdown, and what each sub-plugin covers. This works before purchase — it helps the user decide.
+
+### Recording a purchase
+
+`purchasedPlugins` is an entitlement-bearing field: the effective list derives from the Rubytech-signed entitlement payload, not from raw `account.json`. The pre-tool-use hook denies any agent write to `account.json`. Direct purchase recording is therefore unavailable to the agent.
+
+- **Production path:** the Rubytech-side issuance endpoint signs an updated entitlement payload after a Stripe purchase event and delivers it to `~/<configDir>/entitlement.json`. The verifier picks up the new payload at the next session start.
+- **Pre-launch / dev path:** the founder runs `node platform/scripts/generate-entitlement-fixture.mjs sign --account-id <id> --email <e> --tier <t> --plugins a,b,c --out ~/<configDir>/entitlement.json` to produce a signed test payload. The agent does not invoke this script.
+- **Personal-mode installs (`brand.json.commercialMode: false`, the default today):** purchasedPlugins is read from raw `account.json` via implicit-trust mode. Pre-launch the agent has no way to add purchases without operator intervention; this is intentional during the gap before signed-issuance ships.
+
+If the user asks the agent to record a purchase, explain that their purchase is processed by Rubytech billing and the entitlement payload arrives on their device automatically — no agent action is required.
+
+### Delivering a premium plugin
+
+Call `premium-deliver` with `pluginName` set to the plugin name. The tool handles everything:
+
+- Validates the plugin name and checks purchase status
+- Auto-detects standalone vs bundle (BUNDLE.md vs PLUGIN.md)
+- For bundles: copies each sub-plugin from staging to `$PLATFORM_ROOT/plugins/`
+- For standalone plugins: copies the single plugin directory
+- Skips already-delivered sub-plugins (idempotent)
+- Verifies each copy (PLUGIN.md exists and parses)
+- Updates `enabledPlugins` in account.json (only newly delivered names)
+- Scans for public agent templates
+- Returns a structured result with per-sub-plugin status and available templates
+
+Report the tool's result to the user. If templates are found, present them and ask whether the user wants to create any now. For template creation, run `skill-load skillName=public-agent-manager` and follow the "Create from Template" instructions, passing the template directory path from the tool's result.
+
+If the delivered plugin has specialist agents (files in `agents/` with the `{plugin-name}--{agent-name}.md` naming convention, distinct from template directories), load the specialist management skill and follow the premium plugin agent activation instructions.
+
+### On-demand template listing
+
+Call `premium-deliver` for the plugin — it re-scans templates without re-copying anything (idempotent). The `templates` array in the result contains each template's display name, description, suggested slug, and directory path. `premium-list` returns purchase and delivery status but does not scan templates.
+
+### Disabling a premium plugin or bundle
+
+For standalone plugins and individual sub-plugins: remove the name from `enabledPlugins`. If the plugin has an `agents/` directory, load specialist-management and follow the deactivation instructions. Plugin files remain in `$PLATFORM_ROOT/plugins/` (permanent ownership — never removed).
+
+When the user says "disable {bundle-name}" (e.g., "disable real-agency"), read the `BUNDLE.md` from staging, iterate the `plugins` array, and remove each sub-plugin name from `enabledPlugins`. When they say "disable {sub-plugin-name}" (e.g., "disable estate-coaching"), remove only that name.
+
+## Account Settings
+
+When the user asks to change output style, thinking view, effort, context mode, or model, call `account-update` with the field and value. Changes take effect on the next session.
+
+| Setting | Field | Values |
+|---------|-------|--------|
+| Admin model | `adminModel` | Any Anthropic model ID (e.g. `"claude-sonnet-4-6"`) |
+| Public model | `publicModel` | Any Anthropic model ID (e.g. `"claude-haiku-4-5"`) |
+| Output style | `outputStyle` | `"default"` \| `"explanatory"` |
+| Thinking view | `thinkingView` | `"default"` \| `"expanded"` \| `"collapsed"` |
+| Effort | `effort` | `"low"` \| `"medium"` \| `"high"` \| `"max"` \| `"auto"` |