@stacksjs/defaults 0.75.109 → 0.75.110

package/ai/skills/stacks-desktop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-desktop
-description: Use when building or publishing desktop applications with Stacks - Craft native windows, system tray, desktop packaging, or Mac App Store delivery.
+description: Use when building or publishing desktop applications with Stacks - Craft native windows, local launchers, helper processes, packaging, capability probes, or Mac App Store delivery. Covers @stacksjs/desktop-build and the browser bridge boundary.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -13,7 +13,8 @@ allowed-tools: Read Edit Write Bash Grep Glob
 - Source: `storage/framework/core/desktop/src/index.ts`
 - System tray views: `storage/framework/defaults/views/system-tray/`
 - System tray layouts: `storage/framework/defaults/resources/layouts/`
-- Package: `@stacksjs/desktop`
+- Build/host package: `@stacksjs/desktop-build`
+- Browser bridge package: `@stacksjs/desktop/browser` (from the STX ecosystem)
 
 ## Runtime
 
@@ -86,7 +87,7 @@ interface Desktop {
 
 The launcher Stacks compiles opens a Craft window on the URL in `desktop.json`,
 which is what a hosted Stacks application wants. An app whose subject is the
-machine it runs on — a disk cleaner, a log viewer, a device tool — has no such
+machine it runs on - a disk cleaner, a log viewer, a device tool - has no such
 URL: it starts something locally and opens a window on that, on a port it does
 not know until launch.
 
@@ -95,7 +96,7 @@ same way anything under `app/` overrides its framework default. `DESKTOP_URL`
 and `APP_URL` then become optional, because the launcher decides what to open.
 
 ```ts
-// app/Desktop/launcher.ts — compiled to Contents/MacOS/<AppName>
+// app/Desktop/launcher.ts - compiled to Contents/MacOS/<AppName>
 import { dirname, join } from 'node:path'
 
 const macos = dirname(process.execPath)          // siblings live here
@@ -117,7 +118,7 @@ Two things follow from declaring your own launcher:
   copied into `Contents/MacOS`.** Compile the sibling binaries your launcher
   spawns into that directory and they ship with it.
 - **`app/Desktop/Resources/` is copied into `Contents/Resources`.** A
-  prerendered UI, a schema, seed data — a local-first app has a payload, and
+  prerendered UI, a schema, seed data - a local-first app has a payload, and
   this is where it goes.
 
 `build:dmg` also narrows App Transport Security for these bundles: an exception
@@ -127,7 +128,7 @@ permit every unencrypted host on the internet.
 ### Info.plist entries
 
 `app/Desktop/Info.plist.json` is merged into the generated `Info.plist`. The
-entries that matter most are the `NS*UsageDescription` strings — they are the
+entries that matter most are the `NS*UsageDescription` strings - they are the
 sentences a person reads when macOS asks whether your app may look in their
 Downloads folder or drive Finder, and without them the prompt is generic or the
 request is refused outright.
@@ -144,38 +145,38 @@ JSON, not XML: a malformed plist produces a bundle macOS silently refuses to
 launch, which surfaces long after the build reported success. Strings, numbers,
 booleans, arrays, and nested objects all render.
 
-Keys the bundle must own — `CFBundleIdentifier`, `CFBundleExecutable`,
-`CFBundleVersion`, and the rest of the identity — are ignored with a note.
+Keys the bundle must own - `CFBundleIdentifier`, `CFBundleExecutable`,
+`CFBundleVersion`, and the rest of the identity - are ignored with a note.
 Rewriting those produces a bundle that does not match what was signed.
 
 Inside the bundle the launcher is named after the app, not `stacks-desktop`.
 macOS names the *process* in every permission prompt, so a launcher keeping the
 framework's build name asks "stacks-desktop would like to access files in your
-Downloads folder" — which reads like something to refuse.
+Downloads folder" - which reads like something to refuse.
 
 Application data belongs in `~/Library/Application Support/<AppName>`, never
-inside the bundle — `/Applications` is not writable by the user, and the bundle
+inside the bundle - `/Applications` is not writable by the user, and the bundle
 is replaced wholesale on update.
 
 ## Helper processes: one binary, not three
 
-An app that owns its launcher usually needs more than the launcher — an agent
+An app that owns its launcher usually needs more than the launcher - an agent
 serving on loopback, a worker doing something slow out of process. Compile each
 as its own binary and the bundle gets very large very quietly.
 
 `bun build --compile` embeds the entire Bun runtime in **every** executable it
 writes. `console.log("hi")` measures **60.5 MB**. So three binaries means three
-copies of the same runtime, and nothing says so — the bundle is simply big, and
+copies of the same runtime, and nothing says so - the bundle is simply big, and
 a big desktop app looks unremarkable. One real app shipped 230 MB this way, of
 which about 180 MB was the runtime repeated; its own code plus the native Craft
 runtime came to under 40 MB.
 
 Compile **one** binary and dispatch on a subcommand. The helpers stay separate
-*processes* — which is what actually matters for isolation and for killing one
-that wedges — they just stop being separate *files*.
+*processes* - which is what actually matters for isolation and for killing one
+that wedges - they just stop being separate *files*.
 
 ```ts
-// app/Desktop/launcher.ts — before anything else at module scope
+// app/Desktop/launcher.ts - before anything else at module scope
 const subcommand = process.argv[2]
 
 if (subcommand === 'agent' || subcommand === 'scan') {
@@ -205,7 +206,7 @@ Two things that bite, both silently:
 - **The dispatch must come first.** A launcher's body is top-level code that
   starts a server and opens a window as a side effect of loading.
 - **Do not `process.exit()` after starting a server.** A `runAgent()` that
-  returns once `Bun.serve` is listening has not finished — `Bun.serve` is what
+  returns once `Bun.serve` is listening has not finished - `Bun.serve` is what
   holds the process open. Exiting after it kills the agent one line after it
   printed the port the launcher is still waiting for, and the launcher reports
   a timeout that says nothing about the cause.
@@ -287,6 +288,11 @@ Repository secrets:
 - `APP_STORE_CONNECT_API_ISSUER_ID`
 
 ## Gotchas
+- Configure build identity and browser UI separately; the host build package is
+  not a browser-safe native API import. Verify bridge readiness inside the
+  actual Craft window before enabling native-only flows.
+- Probe results describe the recorded host/runtime version. A successful
+  packaging command is not evidence of input/audio/graphics capability parity.
 - App Store packaging runs on macOS with Xcode command-line tools.
 - The embedded Craft runtime must inherit the parent App Sandbox.
 - A Mac App Distribution identity and Mac Installer Distribution identity serve different signing steps.

package/ai/skills/stacks-development/SKILL.md

@@ -9,7 +9,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 # Stacks Development
 
 ## Key Paths
-- Development package: `storage/framework/core/development/` (stub — exports `{}`)
+- Development package: `storage/framework/core/development/` (stub - exports `{}`)
 - Dev server entry: `storage/framework/server/src/index.ts`
 - Dev server utils: `storage/framework/server/src/utils.ts`
 - Server build script: `storage/framework/server/build.ts`
@@ -32,13 +32,13 @@ actions/src/dev/
 ├── dashboard.ts        # Dashboard dev server (STX + native Craft window + config API)
 ├── dashboard-utils.ts  # Model discovery, sidebar config, icon map, waitForServer()
 ├── docs.ts             # Docs dev server (@stacksjs/bunpress, watch mode)
-├── components.ts       # Components dev server (runs `bun run dev` in libs/components/vue)
+├── components.ts       # Components dev server (native stx component playground)
 ├── desktop.ts          # Desktop dev server (runs `bun run dev` in framework/views/desktop)
 └── system-tray.ts      # System tray dev server (runs `bun run dev` in framework/system-tray)
 
 server/
 ├── src/
-│   ├── index.ts        # Production server entry (Bun.serve, WebSocket, queue worker mode)
+│   ├── index.ts        # Production HTTP server entry (Bun.serve, one-shot queue worker mode)
 │   └── utils.ts        # cleanCopy(), useCustomOrDefaultServerConfig(), buildDockerImage()
 ├── build.ts            # Server build script (Bun.build for ESM, Docker image)
 ├── dev                 # Shell script for running server via Docker with volume mounts
@@ -86,7 +86,7 @@ buddy/src/commands/
 - `buddy dev:api` -- API server only
 - `buddy dev:dashboard` (alias: `dev:admin`) -- Dashboard with native Craft window
 - `buddy dev:docs` -- Documentation server only
-- `buddy dev:components` -- Vue component library dev server
+- `buddy dev:components` -- stx component playground
 - `buddy dev:desktop` -- Desktop app dev server
 - `buddy dev:native` -- Equivalent native app development flow
 - `buddy dev:system-tray` (alias: `dev:tray`) -- System tray dev server
@@ -184,7 +184,7 @@ When `APP_URL` is set to a custom domain (not `localhost`):
 - **Frontend (STX)**: `bun-plugin-stx/serve` has its own built-in watch/HMR for `.stx` templates
 - **API server**: Runs via `bun --watch`, restarts on route or handler changes
 - **Docs**: `@stacksjs/bunpress` runs with `watch: true` for live documentation updates
-- **Components**: Delegates to the component library's own `bun run dev` (typically Vite-based HMR)
+- **Components**: Uses the native component development workflow; inspect core/actions/src/dev/components.ts for the selected entry
 
 ## Preloader (preloader.ts)
 
@@ -226,7 +226,7 @@ linker = "hoisted"
 
 - **Queue worker mode**: When `QUEUE_WORKER` env var is set, imports and runs the job from `app/Jobs/<JOB>.ts` with retry support (configurable via `JOB_RETRIES`, `JOB_BACKOFF_FACTOR`, `JOB_INITIAL_DELAY`, `JOB_JITTER`)
 - **HTTP server**: `Bun.serve()` on `PORT` (default 3000), delegates to `serverResponse()` from `@stacksjs/router`
-- **WebSocket**: Built-in WebSocket upgrade support (open/message/close handlers as stubs)
+- **Realtime**: Separate authenticated broadcast server; the HTTP entry does not upgrade WebSocket requests
 - **Development mode**: Auto-enabled when `APP_ENV` is not `production` or `prod`
 - **Docker**: Multi-stage build with `oven/bun:1.3.10`, runs as non-root `bun` user, exposes port 3000, includes curl for healthchecks
 
@@ -269,13 +269,13 @@ Default configurations provided at `storage/framework/defaults/ide/`:
 ## Doctor Health Checks
 
 `buddy doctor` verifies:
-- Bun runtime version (pass if v1.0+, warn otherwise, fail if missing)
+- Bun runtime version against the installed framework minimum (Bun >= 1.3.0)
 - Node.js version (pass if v18+, warn otherwise)
 - package.json existence and project name
 - `.env` file presence (warn if missing, not a failure)
 - `APP_KEY` is set (warn if not, suggests `buddy key:generate`)
 
-## STX Configuration (config/ui.ts)
+## STX Configuration (config/stx.ts)
 
 ```typescript
 {
@@ -303,3 +303,14 @@ Note: Dashboard mode overrides these settings via its own `serve()` options.
 - The `bun-plugin-stx` serve plugin is resolved with a fallback: first tries normal `import('bun-plugin-stx/serve')`, then falls back to `pantry/bun-plugin-stx/dist/serve.js`
 - `buddy fresh` is NOT the same as `buddy clean` -- `fresh` cleans AND reinstalls dependencies, while `clean` only removes artifacts
 - The Craft native window for the dashboard uses `http://localhost:<port>` directly (not HTTPS) even when a custom domain proxy is running
+
+
+## Verify the selected entrypoint
+
+Use `core/actions/src/dev.ts` and `dev/views.ts` for the actual launch and STX
+request pipeline. Page middleware, API forwarding, request scopes and SEO are
+installed there and in `core/buddy/src/production-server.ts`, not by copying an
+example Bun.serve into a page. Native launch, marketing-site launch and browser
+launch are distinct options; read config/app.ts and buddy dev --help.
+A preloader skip does not mean the selected server never initializes model
+globals: server entrypoints invoke their own runtime boot.

package/ai/skills/stacks-dns/SKILL.md

@@ -8,142 +8,75 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks DNS
 
-## Key Paths
-- Core package: `storage/framework/core/dns/src/`
-- AWS driver: `storage/framework/core/dns/src/drivers/aws.ts`
-- Config: `config/dns.ts`
-- Package: `@stacksjs/dns`
-
-## Source Files
-```
-dns/src/
-├── index.ts              # Re-exports from drivers and @stacksjs/dnsx
-└── drivers/
-    └── aws.ts            # AWS Route53 DNS management
-```
-
-## AWS Route53 API
-
-```typescript
-import {
-  createHostedZone,
-  deleteHostedZone,
-  deleteHostedZoneRecords,
-  getNameservers,
-  getHostedZoneNameservers,
-  updateNameservers,
-  findHostedZone,
-  hasUserDomainBeenAddedToCloud,
-  writeNameserversToConfig,
-  addDomain,
-} from '@stacksjs/dns'
-```
-
-### Hosted Zone Management
-
-```typescript
-// Create or retrieve a hosted zone
-createHostedZone(domainName: string): Promise<Result<HostedZone | CreateHostedZoneResult | string | null, Error>>
-
-// Delete a zone and all its records
-deleteHostedZone(domainName: string): Promise<Result<string, Error>>
-
-// Delete records only, keep zone
-deleteHostedZoneRecords(domainName: string): Promise<Result<string, Error>>
-
-// Find a zone by domain name
-findHostedZone(domain: string): Promise<Result<string | null | undefined, Error>>
-
-// Check if domain is in cloud
-hasUserDomainBeenAddedToCloud(domainName?: string): Promise<boolean>
-```
-
-### Nameserver Management
-
-```typescript
-// Get nameservers from Route53 Domains
-getNameservers(domainName?: string): Promise<string[] | undefined>
-
-// Get nameservers from hosted zone delegation set
-getHostedZoneNameservers(domainName: string): Promise<string[]>
-
-// Update domain nameservers in Route53
-updateNameservers(hostedZoneNameservers: string[], domainName?: string): Promise<boolean | undefined>
-
-// Persist nameservers to config/dns.ts
-writeNameserversToConfig(nameservers: string[]): void
-```
-
-### Domain Actions
-
-```typescript
-// Run domain add action (delegates to CLI action)
-addDomain(options: DeployOptions): Promise<Result<Subprocess, CommandError>>
-```
-
-### Helpers
-
-```typescript
-// Internal helpers
-deleteRecordsForZone(zoneId: string): Promise<void>
-normalizeDomain(domain: string): string
-sanitizeNameserver(ns: string): string
-```
-
-## Configuration (config/dns.ts)
-
-```typescript
-import { defineDns } from '@stacksjs/config'
-
-export default defineDns({
-  a: [{ name: 'example.com', value: '1.2.3.4', ttl: 300 }],
-  aaaa: [],
-  cname: [],
-  mx: [],
-  txt: [],
-  nameservers: [
-    'ns-1731.awsdns-24.co.uk',
-    'ns-355.awsdns-44.com',
-    'ns-536.awsdns-03.net',
-    'ns-1395.awsdns-46.org',
-  ],
-  redirects: [],
-})
-```
-
-### DnsConfig Interface
-
-```typescript
-interface DnsConfig {
-  a: Array<{ name: string, value: string, ttl?: number }>
-  aaaa: Array<{ name: string, value: string, ttl?: number }>
-  cname: Array<{ name: string, value: string, ttl?: number }>
-  mx: Array<{ name: string, value: string, ttl?: number, priority?: number }>
-  txt: Array<{ name: string, value: string, ttl?: number }>
-  nameservers: string[]
-  redirects?: Array<{ from: string, to: string }>
-}
-```
-
-## CLI Commands
-
-```bash
-buddy dns                # DNS management
-buddy domains            # Domain management
-buddy domains:add        # Add a domain to cloud
-buddy domains:remove     # Remove a domain
-buddy domains:purchase   # Purchase a domain
-```
-
-## Re-exports from @stacksjs/dnsx
-
-Additional DNS utilities (lookups, resolution) are re-exported from the `@stacksjs/dnsx` package.
-
-## Gotchas
-- **AWS-only** — currently only supports AWS Route53 as the DNS provider
-- **Uses ts-cloud SDK** — Route53 API calls go through the ts-cloud abstraction
-- **Result type** — most functions return `Result<T, Error>` from `ts-error-handling`, not plain values
-- **`writeNameserversToConfig` mutates config/dns.ts** — directly writes to the config file
-- **Domain name normalization** — trailing dots and www prefixes are handled automatically
-- **`createHostedZone` is idempotent** — returns existing zone if it already exists
-- **Nameservers must be synced** — hosted zone nameservers must match domain registrar nameservers for DNS to work
+Use the native declarative DNS planner for config reconciliation, and Route53
+helpers for hosted-zone/delegation management. Previewing a plan and applying
+provider changes are separate operations.
+
+## Declarative additive sync
+
+~~~ts
+import { syncDnsConfig } from '@stacksjs/dns'
+import { dns, overridesReady } from '@stacksjs/config'
+
+await overridesReady
+const preview = await syncDnsConfig('example.com', dns, { dryRun: true })
+console.log(preview.plan.create, preview.plan.keep, preview.plan.skip)
+~~~
+
+desiredDnsRecords(domain, config) converts native config to provider records.
+planDnsSync(desired, current, { zone? }) returns create/keep/skip with reasons.
+syncDnsConfig(domain, config, { dryRun?, provider? }) reports created/kept/failed,
+failures/skipped/applied/provider. It only creates missing declared records;
+it never deletes or overwrites an existing value. Single-value A/AAAA/CNAME
+records are kept when present; TXT/MX can add distinct values. Editing config
+does not imply changing an already-present provider value.
+
+dryRun reads public DNS without provider credentials; that is not a complete
+zone export. Actual apply selects a ts-cloud DNS provider by domain/nameservers
+and credentials. A missing provider yields an unapplied plan, not fake success.
+The native sync interface supports Route53/Porkbun/GoDaddy/Cloudflare through
+the provider factory; retained request/planner tests are not live provider parity.
+
+## Native config record shapes
+
+config/dns.ts uses a/aaaa records with address, cname with target, txt with
+content, and mx with mailServer/priority. Each has name and optional ttl.
+The older generic value field is not this contract. nameservers describe
+delegation and are not included in desired zone records.
+
+Names @/empty mean the apex; names already in the zone or ending in a dot are
+absolute. A/AAAA address @ copies an apex address declared in the same config;
+without one it is skipped with a reason. CNAME target @ names the apex.
+Private/loopback/placeholder addresses and out-of-zone records are skipped;
+TTL normalization applies the planner's current minimum. Resolve conflicts
+deliberately rather than interpreting keep as identical desired content.
+
+resolveLiveRecords(domain) reads public DNS. renderDnsConfig(domain, records)
+renders source for review; dnsProviderForDomain(domain) resolves the mutable
+provider. Use buddy dns:* --help for pull/sync command flags and output paths.
+
+## Route53 zone and registrar helpers
+
+The public entry also exports createHostedZone, findHostedZone,
+deleteHostedZone/deleteHostedZoneRecords, getNameservers/getHostedZoneNameservers,
+updateNameservers, writeNameserversToConfig and addDomain. Their source is
+drivers/aws.ts; most zone operations return Result and require inspecting isOk.
+Registrar nameservers and hosted-zone delegation are different state. Deleting
+a zone or publishing delegation requires the task's authorization.
+
+writeNameserversToConfig changes config/dns.ts. addDomain delegates to the native
+application action. Normalization, idempotent zone lookup and provider API errors
+are defined by their implementations; use real results instead of assuming
+await means a record was published.
+
+## Boundaries and evidence
+
+`@stacksjs/dns` does not currently re-export dnsx: the dependency's missing
+runtime entry was intentionally removed from the public graph. Use an installed
+working resolver package or native DNS where appropriate, not an import promised
+only by ambient declarations. Deploy mail DNS reconciliation has its own owned
+record policy in buddy, distinct from this strictly additive planner.
+
+Source: `storage/framework/core/dns/src/index.ts`, sync.ts, drivers/aws.ts,
+config/dns.ts and core/types/src/dns.ts. Evidence: core/dns/tests/sync.test.ts
+and dns.test.ts. No live DNS mutations are needed to review the planner.

package/ai/skills/stacks-domain-modeling/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily: only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why*, not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`): useful when decisions are revisited
+- **Considered Options**: only when the rejected alternatives are worth remembering
+- **Consequences**: only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it: you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library: just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it; otherwise someone will suggest GraphQL again in six months.

package/ai/skills/stacks-domain-modeling/GLOSSARY-FORMAT.md

@@ -0,0 +1,60 @@
+# GLOSSARY.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `GLOSSARY.md` at the repo root.
+
+**Multiple contexts:** A `GLOSSARY-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Glossary Map
+
+## Contexts
+
+- [Ordering](src/ordering/GLOSSARY.md): receives and tracks customer orders
+- [Billing](src/billing/GLOSSARY.md): generates invoices and processes payments
+- [Fulfillment](src/fulfillment/GLOSSARY.md): manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `GLOSSARY-MAP.md` exists, read it to find contexts
+- If only a root `GLOSSARY.md` exists, single context
+- If neither exists, create a root `GLOSSARY.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/ai/skills/stacks-domain-modeling/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ai/skills/stacks-domain-modeling/NOTICE.md

@@ -0,0 +1,10 @@
+# Source and license
+
+The upstream MIT notice is preserved in [LICENSE](LICENSE).
+
+## domain-modeling
+
+Source: [skills/engineering/domain-modeling/SKILL.md](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/domain-modeling/SKILL.md),
+revision `49dd158d1076134a641b33efb035946536778336`.
+
+Reviewed against the existing Stacks workflow. Stacks API guidance is retained; current workflow changes and supporting references are integrated where applicable.

package/ai/skills/stacks-domain-modeling/SKILL.md

@@ -24,6 +24,13 @@ Credit: adapted from Matt Pocock's `domain-modeling` skill (MIT),
 
 ## File structure
 
+Honor the existing domain source. A project using `GLOSSARY.md` or
+`GLOSSARY-MAP.md` keeps that layout; a project using `CONTEXT.md` keeps this
+skill's existing layout. Follow map pointers to the relevant context rather
+than putting every bounded context into one glossary. Keep definitions about
+domain meaning; specs and ADRs hold implementation decisions. The updated
+glossary-only template is [GLOSSARY-FORMAT.md](GLOSSARY-FORMAT.md).
+
 Most repos have a single context:
 
 ```
@@ -104,6 +111,10 @@ If any of the three is missing, skip it.
 
 ## Downstream
 
+`stacks-grill-with-docs` combines this discipline with `stacks-grilling`.
+Current upstream provenance is in [NOTICE.md](NOTICE.md); read
+[the Stacks adaptation rules](../stacks-flow/ENGINEERING.md) with this workflow.
+
 > Reach for `stacks-codebase-design` when the argument is about a module's
 > shape rather than its name, and `stacks-grilling` when the term will not
 > settle without an interview.