@cratis/pi 0.0.1 → 2.0.1

package/package/corpus/skills/cratis-engineering-csharp-conventions/references/exceptions-logging-and-di.md

@@ -0,0 +1,223 @@
+# Exceptions, logging, and dependency injection
+
+## Exceptions
+
+Every exception type communicates *what went wrong in domain terms*. A built-in
+`InvalidOperationException` says nothing; a domain `AuthorAlreadyRegistered`
+says everything.
+
+- Throw only for genuinely exceptional situations, never for control flow.
+- Always define a custom type deriving from `Exception`. Never throw a built-in
+  exception type.
+- Never suffix the type name with `Exception`.
+- Always supply a meaningful message.
+- Document the type with an XML summary starting "The exception that is thrown
+  when …".
+- Never write an empty or silently swallowing `catch`. Handle it, log it, or let
+  it propagate. When ignoring is genuinely correct, use an exception filter
+  (`catch (<ExceptionType>) when (<condition>)`) whose body states the decision
+  through a comment or a fallback — never a bare `catch { }`.
+
+```csharp
+/// <summary>
+/// The exception that is thrown when <condition>.
+/// </summary>
+/// <param name="<parameterName>">The <see cref="<ParameterType>"/> that <description>.</param>
+public class <DomainExceptionName>(<ParameterType> <parameterName>)
+    : Exception($"<message> '{<parameterName>}' <detail>");
+```
+
+```csharp
+var <identifier> = await <source>.<FindMethod>(<argument>)
+    ?? throw new <DomainExceptionName>(<argument>);
+```
+
+## Logging
+
+- Use structured logging with named parameters.
+- Inject `ILogger<T>` where `T` is the containing class.
+- Keep message definitions in a separate `<ClassName>Logging.cs` file as a
+  `static partial` internal class.
+- Use the `[LoggerMessage]` attribute and do **not** supply an `eventId`.
+- Choose the level deliberately: `Information`, `Warning`, `Error`, `Debug`.
+
+```csharp
+// <ClassName>Logging.cs
+namespace <RootNamespace>.<Feature>;
+
+static partial class <ClassName>Logging
+{
+    [LoggerMessage(LogLevel.Information, "<message> '{<Parameter>}'")]
+    internal static partial void <MessageName>(
+        this ILogger<<ClassName>> logger, <ParameterType> <parameter>);
+}
+```
+
+```csharp
+public class <ClassName>(ILogger<<ClassName>> logger)
+{
+    public Task <MethodName>(<ParameterType> <parameter>)
+    {
+        logger.<MessageName>(<parameter>);
+        <statement>;
+    }
+}
+```
+
+## Dependency injection
+
+The framework discovers and wires dependencies by convention. Explicit
+registration is the exception, not the rule.
+
+- Prefer constructor injection. Never inject `IServiceProvider` to resolve
+  collaborators — that is the service-locator anti-pattern.
+- Mark a singleton with the `[Singleton]` attribute rather than registering it
+  explicitly.
+- A convention-based `IFoo → Foo` pair needs no registration.
+- Command and query `Handle()` parameters resolve from DI by type.
+
+```csharp
+// Preferred — constructor injection
+public class <ClassName>(<ICollaboratorType> <collaborator>);
+
+// Avoid — service locator
+public class <ClassName>(IServiceProvider provider)
+{
+    void <MethodName>() =>
+        provider.GetService<<ICollaboratorType>>()!.<Method>();
+}
+```
+
+## Service lifetimes — `[Singleton]` is a narrow choice
+
+**Assume every application is multi-tenant**, even when it ships with a single
+tenant and no tenant resolution configured. A single-tenant application is a
+multi-tenant one with one tenant in it, and the code shape that serves both is
+the same. The shape that serves only one has to be found and rewritten later,
+from the far side of a data migration, in production.
+
+That gives one rule with two faces:
+
+> **A singleton may not depend on anything that belongs to a tenant, a user, or
+> a request.**
+
+These resolve **per scope**, and the scope carries the tenant, so none may be
+injected into a `[Singleton]`:
+
+| Off limits in a singleton | Why |
+| --- | --- |
+| The scoped event store and everything reached from it — event log, read models, constraints, event types, projections, reducers, PII | Resolved for the scope's namespace |
+| A MongoDB collection, database, or client | The database name resolves per scope from the current tenant |
+| An EF Core `DbContext` | Scoped for the same reason, and not thread-safe |
+| A read model injected directly by key | Same scope, same binding |
+| Any held tenant, principal, claims, correlation id, or HTTP context **value** | Belongs to one request and would outlive it |
+
+A `[Singleton]` taking one of these is a **captive dependency**: the container
+hands it the *root* scope's instance and keeps it for process lifetime. The root
+scope has no request, so it resolves no tenant — every read and write goes to
+the default namespace forever, regardless of who is asking.
+
+**It does not throw. It returns nothing.** A query against the wrong namespace
+hits a database that exists and is empty, so the caller receives an empty
+collection, a null read model, or a default-valued options object and carries
+on. The application starts, pages render, the build is green, and configuration
+a tenant spent an afternoon entering is simply absent. It is invisible while
+there is one tenant; every symptom appears the day a second arrives.
+
+**What to use instead.** Default to the convention (transient), which inherits
+the resolving scope's tenant for free, or a scoped lifetime when a service must
+be shared within one request. Reserve `[Singleton]` for what is genuinely
+process-wide and holds no tenant-, user-, or request-bound state: implementation
+aggregators, HTTP client wrappers, options readers, pure computation, framework
+plumbing.
+
+When something must be a singleton and still needs data — a hosted service, a
+dispatcher, a poller — inject `IServiceScopeFactory` and open a scope per unit
+of work:
+
+```csharp
+// Wrong — the scoped collaborator captures the root scope's default namespace forever
+[Singleton]
+public class <ClassName>(<IScopedCollaboratorType> <collaborator>) : <IInterfaceName>
+{
+    public Task<<ResultType>?> <MethodName>() => <collaborator>.<Method>(<argument>);
+}
+
+// Right — a scope per call, so collaborators bind to the caller's tenant
+[Singleton]
+public class <ClassName>(IServiceScopeFactory scopeFactory) : <IInterfaceName>
+{
+    public async Task<<ResultType>?> <MethodName>()
+    {
+        using var scope = scopeFactory.CreateScope();
+        var <collaborator> = scope.ServiceProvider
+            .GetRequiredService<<IScopedCollaboratorType>>();
+
+        return await <collaborator>.<Method>(<argument>);
+    }
+}
+```
+
+A client that names its store and namespace explicitly **is** singleton-safe,
+and is the right collaborator when a flow knows which namespace it means and has
+no scope to resolve one from. Naming the namespace is a deliberate, readable
+statement that this code crosses a tenant boundary; capturing a scoped service
+is the same crossing made by accident.
+
+**The current user is not process-wide either.** Never keep the signed-in user,
+their principal, claims, roles, or anything derived from them in a singleton.
+The distinction that matters: *the accessor is fine, the value is not.* An HTTP
+context accessor is itself a singleton and safe to inject; reading a value out
+of it once and keeping it is not. A current-user service may be a singleton only
+when every method reads through the accessor on each call and stores nothing.
+Anything that derives something per user and wants to keep it holds a cache
+**keyed by the user**, never a single field.
+
+**Off-request work carries its tenant.** Reactors, hosted services, background
+dispatch, and scheduled jobs run with no request, so a tenant resolver has
+nothing to read. Observers may be instantiated per namespace, but the
+collaborators they call are not — a flow that reaches a tenant-blind singleton
+has left its namespace behind without saying so. Such a flow states its tenant
+explicitly rather than inheriting whatever the root scope happens to be.
+
+## Discovering implementations — `IInstancesOf<T>`, never `IEnumerable<T>`
+
+When a type needs every implementation of an abstraction — handlers, strategies,
+filters, validators, formatters — inject `IInstancesOf<TInterface>` from
+`Cratis.Types`. The framework discovers and instantiates every implementation by
+convention, so no explicit registration exists anywhere.
+
+```csharp
+// Wrong — hand-maintained registrations. A new implementation added elsewhere
+// silently does nothing until someone remembers this file, and dead
+// registrations linger after types are removed.
+services.AddSingleton<<IHandlerType>, <FirstHandler>>();
+services.AddSingleton<<IHandlerType>, <SecondHandler>>();
+
+public class <AggregatorName>(IEnumerable<<IHandlerType>> handlers) : <IAggregatorType>;
+
+// Right — implementations discovered automatically
+[Singleton]
+public class <FirstHandler>(<CollaboratorType> <collaborator>) : <IHandlerType>;
+
+[Singleton]
+public class <SecondHandler>(<CollaboratorType> <collaborator>) : <IHandlerType>;
+
+[Singleton]
+public class <AggregatorName>(IInstancesOf<<IHandlerType>> handlers) : <IAggregatorType>;
+```
+
+Rules:
+
+- Never inject `IEnumerable<TInterface>` to enumerate implementations of an
+  abstraction. That signature works only when every implementation is
+  hand-registered, which defeats convention-based discovery.
+- Never register a type that exists to be discovered. Mark it `[Singleton]`, or
+  rely on the `IFoo → Foo` convention for a transient, and delete the
+  registration line.
+- `IInstancesOf<T>` resolves at the point of access, so an implementation added
+  later in the assembly becomes available without touching the consumer or any
+  composition root.
+- `IEnumerable<T>` remains the right type to **return** from a method that
+  yields a sequence of values. The rule applies only to enumerating
+  *implementations* of an abstraction.

package/package/corpus/skills/cratis-engineering-decision-record/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the canonical Cratis/AI repository for the full license text.

package/package/corpus/skills/cratis-engineering-decision-record/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: cratis-engineering-decision-record
+description: Consult, author, accept, and supersede decision records in a Cratis repository's decisions/ folder. Use before an architectural, contract, scope, or cross-cutting change, when a ruling has been made that later work must obey, or when an accepted decision has to be replaced. Defer product documentation, session handovers, and work-item status to their own workflows.
+license: LICENSE
+---
+
+# Cratis decision records
+
+A decision is a durable choice with a **decider** and a **date**. It is
+documentation, not a work record: it lives in the repository's `decisions/`
+folder and is reviewed like any other documentation. A handover may summarize a
+decision; it never holds the only copy.
+
+This skill owns the *procedure* — how to consult, author, accept, and supersede
+a record. It does not decide what to decide, and it never grants acceptance.
+
+## When you need this
+
+- You are about to make an architectural, contract, scope, or cross-cutting
+  change. Consult first: a decision you did not read still binds the change.
+- A ruling was made — in review, in chat, in a meeting — that later work has to
+  obey. Record it in the same turn, while the reasoning is still available.
+- An accepted decision no longer holds and has to be replaced, narrowed, or
+  qualified.
+- Your change would contradict an accepted record. Stop: supersession or a human
+  verdict comes first, never a workaround.
+
+## When you do not
+
+- **Session notes, plans, handovers, status boards.** Those are work records.
+  They belong in the repository's ignored local working directory, never in
+  `decisions/`.
+- **Product or API documentation.** A record says what was chosen and why; the
+  documentation says how the thing works. Use the documentation workflow.
+- **A work item's status.** "Blocked on X" is a work item field, not a decision.
+- **A reversible choice inside your own scope that nobody will re-litigate.**
+  Make it and move on; see the significance test in step 2.
+- **A decision this repository does not own.** Company-level and portfolio
+  decisions live in the record set that owns them. Cite that id; do not copy the
+  record into a repository that cannot supersede it.
+
+## Steps
+
+1. **List the records in force for the paths you are changing.** Read
+   `decisions/`, keep the records whose `applies-to` matches a path you are
+   about to touch and whose `status` is `accepted`, and order them newest first.
+   Report the count — "0 records matched" and "3 matched, none contradicted" are
+   different verdicts and must read differently.
+2. **Cite what you relied on.** Name the ids on the work item, in the pull
+   request body, and as a `Decision: <id>` commit trailer. A change that
+   silently contradicts an accepted record is a defect even when the code is
+   correct.
+3. **Apply the significance test before writing anything.** Write a record only
+   when at least one of these holds: someone will otherwise re-litigate the
+   choice; it binds paths beyond the one you are changing; reversing it would
+   cost real migration or rework; or it rejects an option a reasonable reader
+   would reach for. If none holds, say so and make the change without a record.
+4. **Pass the completeness gate, or open with `status: returned`.** A proposed
+   record states the options considered *including the one not taken and why*,
+   the default that applies if the question is never answered and what that
+   default costs, the timeline the decision has to hold to, and what is in scope
+   and out. A record missing any of the four is returned to its proposer for
+   revision — `returned` is not a rejection.
+5. **Write the verification criterion before acceptance, not after.** State the
+   observable signal that will say the decision was actually carried out, as
+   `Done when` and `Verify by`. A decision whose success cannot be observed
+   cannot reach `stage: verified`.
+6. **Open the record as `status: proposed`, `stage: none`, and regenerate the
+   index.** A record the index does not list is a record the consult step in
+   step 1 will never find.
+7. **Accept by recording a resolved actor and a date.** Set `status: accepted`,
+   `decided` to the date, and `decider` to a named person — never a role, a
+   team, or a tool. Acceptance is a human verdict: draft it, do not grant it.
+8. **Spawn the build work carrying the criterion verbatim.** The `Done when` and
+   `Verify by` text written in step 5 travels onto the work item unchanged, so
+   the thing that gets built is the thing that was decided.
+9. **Move `stage` only on the evidence the next stage requires.** `none` →
+   `implemented` when the change exists in the tree; `implemented` → `verified`
+   only on a signal observed this time. Accepted is not implemented, and
+   implemented is not verified.
+10. **Supersede rather than rewrite.** Never edit an accepted record's decision
+    text in place — that text is what people relied on. Correct a typo or add
+    context under a dated banner that says what changed and why. Change the
+    *choice* only with a new record.
+11. **Point both ways and sweep the citations.** The new record names the one it
+    replaces in `supersedes`; the replaced record's `status` becomes
+    `superseded` and it gains a `superseded-by` pointer forward, with its
+    original text preserved. Then find every work item, pull request body, and
+    commit trailer citing the old id and point it at the new one. A reader
+    arriving at either record must be able to reach the other.
+
+The exact front-matter fields, the closed value sets, and the index shape are in
+[record-format.md](references/record-format.md).
+
+## What breaks
+
+- **A role in the `decider` field.** "The architecture team decided" names
+  nobody who can be asked what they meant or who can supersede it. The record
+  reads as authority but resolves to no one.
+- **Decision text edited in place.** The next reader sees text nobody ever
+  agreed to, and the people who relied on the old wording have no way to tell
+  what changed. This is the failure that makes a whole `decisions/` folder
+  untrustworthy, because it is invisible.
+- **A one-way supersession.** The new record says it supersedes the old one, but
+  the old one still reads as accepted. Whoever arrives from a search, a
+  citation, or an old pull request follows a decision that was replaced.
+- **`stage: verified` set on a green build.** Compilation proves it builds, not
+  that the decision was carried out. The stage then lies about the only thing it
+  exists to say.
+- **A ruling that stayed in chat.** It binds the next change and nobody can find
+  it. The symptom is the same argument being had a second time, with a different
+  outcome.
+- **One record settling three questions.** It cannot be superseded for one of
+  them, so it survives past the point where a third of it is wrong.
+- **An `applies-to` that matches nothing.** Step 1 returns zero records and reads
+  as "nothing binds this change" instead of "the glob is wrong". Report the count
+  so an empty result is visible rather than reassuring.
+
+## How it is proven
+
+- **Consult ran and found something specific.** The count from step 1 appears in
+  the report, and the ids it returned appear on the work item, in the pull
+  request body, and in a `Decision:` commit trailer.
+- **Acceptance resolves.** The record carries a `decided` date and a `decider`
+  that names a person you could actually ask.
+- **Supersession is traversable.** Follow `superseded-by` forward and
+  `supersedes` back; both land on the other record. Search the repository for
+  the superseded id and confirm no live citation still points only at it.
+- **The stage matches the evidence.** `implemented` is confirmed by the change
+  being in the tree; `verified` is confirmed by naming the signal — the command,
+  the gate, the observed behavior — that was watched *this time*.
+- **The index resolves.** Every record in `decisions/` appears in the index, and
+  every index entry resolves to a file.

package/package/corpus/skills/cratis-engineering-decision-record/references/record-format.md

@@ -0,0 +1,107 @@
+# Decision record format
+
+The shape below is the one Cratis repositories that keep a `decisions/` folder
+converge on. A repository that already defines a stricter local shape stays
+authoritative; add fields there rather than dropping the ones listed here.
+
+## Front matter
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `id` | Yes | Stable identifier, unique in the repository, never reused after supersession. |
+| `title` | Yes | The single question the record settles, stated as a choice. |
+| `status` | Yes | Where the record stands in its own review lifecycle. Closed set below. |
+| `stage` | Yes | How far an accepted decision has travelled from words into observed behavior. Closed set below. |
+| `class` | Yes | What kind of choice this is, which sets who may settle it. Closed set below. |
+| `reversibility` | Yes | What undoing it would cost. Closed set below. |
+| `decided` | On acceptance | The date the decision was accepted. |
+| `decider` | On acceptance | A named person. Never a role, a team, or a tool. |
+| `applies-to` | Yes | The paths this record binds, as globs. What the consult step matches against. |
+| `supersedes` | When replacing | The id of the record this one replaces. |
+| `superseded-by` | When replaced | The id of the record that replaced this one. |
+
+`status` and `superseded-by` move together: a record marked `superseded` without
+a forward pointer strands every reader who arrives at it.
+
+## Closed value sets
+
+Do not invent a word for a state one of these sets already names.
+
+**`status`**
+
+| Value | Meaning |
+| --- | --- |
+| `proposed` | Written and offered for a verdict; not yet in force. |
+| `returned` | Sent back to the proposer for revision; not a rejection. |
+| `accepted` | In force; binding on work that touches the paths it covers. |
+| `rejected` | Refused; the choice it proposed is not taken. |
+| `deferred` | Deliberately not settled yet, with the reason recorded. |
+| `superseded` | Replaced by a later record, which it points at. |
+
+**`stage`**
+
+| Value | Meaning |
+| --- | --- |
+| `none` | Accepted, but nothing has been built against it yet. |
+| `implemented` | The change the decision calls for exists in the tree. |
+| `verified` | A signal observed this time confirms the implementation. |
+
+**`class`**
+
+| Value | Meaning |
+| --- | --- |
+| `strategy` | Direction, portfolio, or ownership of a body of work. |
+| `contract` | An interface, schema, protocol, or release boundary others build on. |
+| `product` | What is built, for whom, and what it promises. |
+| `working` | A local, reversible choice inside one team's own scope. |
+
+**`reversibility`**
+
+| Value | Meaning |
+| --- | --- |
+| `reversible` | Undone at negligible cost; decide fast and revisit. |
+| `costly` | Undone, but only by paying real migration or rework cost. |
+| `irreversible` | Cannot be undone; requires a human verdict before acting. |
+
+`class` and `reversibility` together say who may settle the record. A `strategy`
+or `irreversible` record is never accepted by an agent.
+
+## Body sections
+
+A record's body carries, in this order:
+
+1. **Context** — the situation that forced a choice, and what changes if nobody
+   chooses.
+2. **Decision** — the choice, in one paragraph, in the present tense. This is the
+   text that is never edited in place once the record is accepted.
+3. **Options considered** — including the one not taken and why. This is the part
+   a future reader needs most and the part nobody remembers.
+4. **Default if unanswered** — what happens if the question is never settled, and
+   what that costs. A record without this cannot be weighed against doing nothing.
+5. **Timeline and scope** — the horizon the decision holds to, what is in scope,
+   and what is explicitly out.
+6. **Verification** — `Done when` and `Verify by`, written before acceptance. The
+   observable signal that says the decision was carried out.
+7. **Consequences** — what this makes easier, what it makes harder, and what it
+   forecloses.
+
+## Corrections after acceptance
+
+A typo fix or added context goes under a dated banner inside the record:
+
+```markdown
+> **2026-03-04 — clarification.** The decision text below said "client"; every
+> use of that word means the generated client SDK, not a consuming application.
+> The choice itself is unchanged.
+```
+
+Anything that changes the choice is a new record with two-way pointers, not a
+banner.
+
+## Index
+
+The folder carries an index listing every record with its id, title, status,
+stage, decided date, and decider. The index is regenerated whenever a record is
+added or its status changes; a record the index omits is a record the consult
+step will never find. Two checks keep it honest: every file in the folder appears
+in the index, and every index entry resolves to a file.

package/package/corpus/skills/cratis-engineering-docs-authoring/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the canonical Cratis/AI repository for the full license text.

package/package/corpus/skills/cratis-engineering-docs-authoring/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: cratis-engineering-docs-authoring
+description: Draft accurate Cratis documentation content after the owning repository, page placement, document type, and authoritative product sources are known. Use for tutorials, how-to guides, explanations, and references; defer placement, existing-page discovery, and visual QA to their companion workflows.
+license: LICENSE
+---
+
+# Cratis documentation authoring
+
+Draft one accurate Cratis documentation page in the voice and structure required
+by its document type. This skill owns **content**. It does not decide which
+repository owns a page, wire site navigation, locate an existing source page, or
+perform visual QA.
+
+## Required inputs
+
+Before drafting, establish:
+
+- the owning repository and destination page;
+- document type: tutorial, how-to, explanation, or reference;
+- target reader and the outcome they need;
+- authoritative product source for every API, command, version, and capability;
+- explicit scope and important exclusions.
+
+Use repository evidence to resolve routine details. Ask only when materially
+different document types, audiences, or product choices remain plausible.
+
+## Route near misses
+
+- New-page placement or navigation is unresolved: defer to
+  `cratis-engineering-docs-add-page`.
+- The request changes an existing page whose source location is unresolved:
+  defer to `cratis-engineering-docs-edit-page`.
+- The request is to render, screenshot, or diagnose visual layout: defer to
+  `cratis-engineering-docs-visual-qa`.
+- A product/API claim lacks first-party source evidence: stop and identify the
+  missing authority instead of drafting the claim.
+- The subject is not Cratis product or engineering documentation: do not apply
+  this skill.
+
+## Write one document type
+
+Do not mix Diátaxis types on one page:
+
+| Type | Reader need | Shape |
+| --- | --- | --- |
+| Tutorial | Learn by completing a guided outcome | Ordered steps with visible results |
+| How-to | Solve one concrete problem | Prerequisites, direct procedure, completion check |
+| Explanation | Understand why and when | Concepts, boundaries, trade-offs, diagram |
+| Reference | Look up exact information | Exhaustive tables, fields, commands, signatures |
+
+For the detailed mechanical format, read
+[site-format.md](references/site-format.md).
+
+## Drafting workflow
+
+1. Open with the reader's concrete friction and the Cratis capability that
+   relieves it.
+2. Organize by the reader's workflow, not by implementation namespaces or an
+   alphabetical API dump.
+3. Use active voice, present tense, second person, and American English.
+4. Explain the invisible behavior after each example: what the framework does
+   and why the boundary matters.
+5. Verify every API and command against first-party source at the applicable
+   revision. Never translate a C# example into another client language by guess.
+6. State maturity, authorization, side effects, unsupported surfaces, and when a
+   simpler approach is better.
+7. Show a visible result in tutorials and procedures. Use Mermaid for a
+   non-trivial explanation.
+8. End with the natural next page or workflow.
+
+## Correctness boundary
+
+Never invent product APIs, customer claims, versions, support commitments,
+marketplace availability, or private implementation details. Do not copy a code
+sample from memory. If the source cannot prove a claim, omit it or mark the gap
+for the owning maintainer.
+
+A successful build proves rendering, not technical correctness. The owning
+repository still runs its documentation, snippet, link, and product gates.
+
+## Output
+
+Return or write the page content only at the already approved destination. Do
+not modify navigation, generated copies, project context, credentials, package
+manifests, or unrelated documentation. Report the authoritative source checked
+and the verification that still remains.

package/package/corpus/skills/cratis-engineering-docs-authoring/references/site-format.md

@@ -0,0 +1,46 @@
+# Cratis documentation site format
+
+Use these rules for a page that will render on the Cratis Astro Starlight site.
+The owning repository remains authoritative when it defines a stricter format.
+
+## Frontmatter and headings
+
+- Include `title` and `description` frontmatter.
+- Do not add a body H1; the site renders the title as H1.
+- Start body sections at H2.
+- Use sentence case and no trailing punctuation in headings.
+- Keep the page's main workflow visible in H2 sections.
+
+## Code and commands
+
+- Tag every code fence with its language.
+- Dedent copied snippets to their natural source indentation.
+- Use complete, runnable examples without ellipses.
+- Verify examples against first-party product source.
+- Use the client-owned multi-language snippet mechanism when shared product docs
+  support more than one client; do not hand-translate unsupported clients.
+
+## Links and navigation
+
+- Use descriptive link text, never "here" or "read more."
+- Use root-relative links between products.
+- Keep site-level links extensionless.
+- Preserve the owning product repository's source-link convention.
+- Do not edit generated synchronized pages; edit the owning source repository.
+
+## Tables, asides, and diagrams
+
+- Use GitHub-Flavored Markdown tables with a spaced separator row.
+- Use Starlight or owning-repository note/caution syntax for boundaries and
+  security warnings.
+- Use Mermaid for architecture, sequence, or state explanations.
+- Give images meaningful alternative text.
+
+## File hygiene
+
+- Use American English.
+- End the file with one newline.
+- Keep project paths, credentials, local endpoints, and private data out of
+  shared documentation.
+- Run the owning repository's build, lint, snippet, and link checks before
+  calling the page complete.

package/package/corpus/skills/cratis-engineering-effect-boundaries/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the canonical Cratis/AI repository for the full license text.