# Platform overview (/docs)
The public extension model for turning measurable pursuits into purposeful practice, trustworthy progress, and synchronized stories.
Chasing Mastery is a club and creator platform for measurable pursuits. Members
join a shared **Pursuit**, practice through reusable **Practice Modes**, record
atomic **Attempts**, follow independent progression, work toward focused
**Sprints**, and optionally turn verified activity into stream presentation and
production evidence.
The extension platform lets you build the part that understands a domain
without giving portable code account, network, filesystem, device, or media
authority.
## Choose the thing you are building [#choose-the-thing-you-are-building]
## One rule explains the architecture [#one-rule-explains-the-architecture]
The package decides what an observation **means**. The host decides whether it
is authorized, where it is routed, what time it happened, and how committed
evidence is persisted. The connector observes a source; it does not score an
Attempt. An overlay presents committed truth; it never creates it.
This split is what makes rich third-party experiences possible without turning
every package into a trusted application.
## What “supported” means [#what-supported-means]
Chasing Mastery does not consider a vertical supported because it has a timer or
a generic metric form. A launch-quality vertical is a **deep capability stack**:
The [Darts case study](/docs/verticals/darts-reference) demonstrates this entire stack
through the same public contracts available to an external author.
## The fastest route to working bytes [#the-fastest-route-to-working-bytes]
### Understand the Attempt [#understand-the-attempt]
Write down when one unit of practice begins, which inputs are allowed, what
makes it terminal, and which Measurements make two results comparable.
### Bootstrap with the Author plugin [#bootstrap-with-the-author-plugin]
Choose [Codex, ChatGPT, or Claude](/docs/get-started/build-with-an-agent), then
ask the same Chasing Mastery Author workflow to build the experience. It creates a
standalone project with a pinned project-local toolchain; no platform checkout
or global Chasing Mastery CLI is required.
### Exercise the real artifact [#exercise-the-real-artifact]
Use Workbench to drive the actual reducer, player, overlay, observations,
progression, Story Events, corrections, coordination, and narration across
member and broadcast viewports.
### Produce immutable release evidence [#produce-immutable-release-evidence]
Run conformance and `ready`, inspect the deterministic `.cmpkg`, digest, and
submission handoff, then submit it through the authenticated private review
flow.
Continue with [Get started](/docs/get-started) for the five-minute mental model
and first build.
---
# Attempt lifecycle (/docs/concepts/attempt-lifecycle)
Design one atomic unit of practice that completes cleanly, replays exactly, and never depends on an enclosing session.
## The atomic unit [#the-atomic-unit]
An Attempt begins when the package initializes one Practice Mode execution and
ends when the package returns a terminal transition or the member explicitly
aborts it. A completed Attempt is terminal by itself.
Examples:
* one Around the Clock game from target 1 through 20;
* one 60-second Puzzle Rush;
* one complete speedrun or one segment drill;
* one set of 20 reaction stimuli;
* one attempt to perform a memorized sequence.
## Runtime sequence [#runtime-sequence]
### Describe [#describe]
The engine explains accepted inputs, Measurements, result contract, and
capabilities for one configuration. Description is pure and does not begin an
Attempt.
### Initialize [#initialize]
The host supplies a pinned package identity, trusted run identity, actor and
configuration context. The engine returns initial package state and semantic
effects.
### Apply [#apply]
Each typed command or exact observation passes through the same deterministic
reducer. The transition returns replacement package state, optional
Measurements/effects, and terminal status.
### Commit [#commit]
The host validates the transition and commits authoritative activity evidence
with idempotency and expected-revision protection.
### Project [#project]
Progression, history, Story Events, overlays, narration, and creator evidence
consume the committed result. Their projections are rebuildable.
## Repeated intent [#repeated-intent]
Portable UI may reconnect, resume from background, or repeat an action while a
network response is delayed. The host and package protocol use stable command
identity and expected revisions so repeated intent cannot create a duplicate
Attempt or apply a throw twice.
## Abort is explicit [#abort-is-explicit]
Walking away after a completed Attempt requires no Stop button. Walking away
halfway through a live Attempt may require Abort so the system can distinguish
intentional abandonment from an interrupted connection and keep history
honest.
---
# Evidence becomes story (/docs/concepts/evidence-and-story)
Preserve practice truth once, then derive progression, presentation, creator moments, and production evidence safely.
## Evidence hierarchy [#evidence-hierarchy]
```text
raw source event
→ exact observation
→ package transition
→ committed Attempt + Measurements
→ Story Events
→ media anchors and sealed creator evidence
→ Content Studio intake
```
Each layer adds meaning without rewriting the layer below it.
## Measurements [#measurements]
Measurements are typed results attached to an Attempt or another explicit
subject. A primary comparable metric might be elapsed milliseconds, accuracy,
score, mistakes, or a bounded pass/not-yet result. Supporting Measurements may
explain the result without determining progression.
## Progression [#progression]
Progression selects comparable Attempts using immutable package policy,
aggregates the relevant evidence, and maps it to thresholds. The resulting rank
state is cached for fast product reads but can always be rebuilt from the
authoritative history.
## Story Events [#story-events]
The package emits semantic facts such as:
```ts
{
kind: "story.emit",
eventType: "personal_best",
facts: { previousMs: 45120, currentMs: 42800 }
}
```
Consumers decide how to present or edit that fact. The package does not name a
video file, control OBS, call a voice provider, or upload media.
## Media anchors [#media-anchors]
Station owns capture clocks. The host maps committed Story Events to bounded
time windows in one capture, preserving clock provenance and gaps. An editor
can find “the rank-up throw” without trusting a package-supplied file offset.
## Corrections [#corrections]
Correcting committed evidence creates an immutable later revision. The host
replays pinned package bytes, rebuilds derived state, retracts invalidated Story
Events, and preserves both revisions for audit. See
[Correction and exact replay](/docs/packages/corrections).
---
# Immutable releases and comparable results (/docs/concepts/immutability)
Evolve visuals and behavior without silently changing what historical evidence means.
Every package release is immutable. An active run pins the exact release and
capability versions it began with. Publishing `1.2.1` never mutates `1.2.0` and
never changes the code used to replay its Attempts.
## Three compatibility questions [#three-compatibility-questions]
1. **Presentation:** can the UI or overlay change without changing results?
2. **Result contract:** do identical inputs still produce comparable primary
evidence?
3. **Progression:** does the same evidence map through the same aggregation and
threshold policy?
A visual polish release may preserve both result and progression lanes. Fixing
a scoring bug may deliberately create a new result lane. Changing rank
thresholds may preserve the result lane while creating a new progression
definition.
## Prove evolution [#prove-evolution]
Do not declare compatibility in prose. Run the package-local evolution command
against the exact prior archive. It performs structural checks and differential
fixture execution, then reports which lanes may remain comparable.
```bash
npm run cm -- evolution --from ./releases/my-package-1.2.0.cmpkg
```
The old archive remains untouched. Rollback changes which immutable release is
selected; it never rewrites installation or Attempt history.
---
# Core concepts (/docs/concepts)
Understand the stable ideas that every Chasing Mastery vertical composes.
The public platform has a small number of deliberately strict concepts. Learn
these before the exact schemas; they tell you which schema should exist and
which component can safely own it.
## Composition, not privilege [#composition-not-privilege]
Official packages are reference implementations of public contracts. If an
official experience needs something that an external author cannot express,
the correct response is to improve the public boundary with representative
fixtures and conformance—not reach into a private host module.
That dogfooding rule is how Darts became useful infrastructure for Chess,
speedrunning, memory training, browser activities, and future verticals.
---
# Trust and authority (/docs/concepts/trust-boundary)
The package knows the domain; the host owns identity, time, persistence, devices, and recovery.
## Portable package boundary [#portable-package-boundary]
A package may own deterministic rules, package state, Measurements,
progression definitions, portable presentation, Story Event vocabulary,
coordination policy, narration policy, and correction interpretation.
It does **not** receive direct account, database, credential, provider-secret,
filesystem, network, native API, OBS, or media-storage authority. Portable UI
runs in an opaque iframe or WebView and communicates through one bounded typed
bridge.
## Host boundary [#host-boundary]
The host supplies authenticated actor identity, active run routing, trusted
timestamps, expected revisions, idempotency keys, package-release pins, source
bindings, persistence, recovery, and capability grants. It validates every
package output before committing it.
## Connector boundary [#connector-boundary]
A Station connector is native code, so it travels through a stricter lane. The
default sidecar begins with no ambient authority. Station grants only reviewed
capabilities such as a narrow private-LAN connection, a specific file read, or
a supervised process interaction. Revocation terminates the authority.
The connector emits exact observations. It cannot decide which member,
Practice Mode, Attempt, or Sprint receives them.
## Derived consumers [#derived-consumers]
Overlays, narration, recording, media anchoring, editorial processing, and
Content Studio are downstream of a committed activity transition. Their
failure must never roll back or delay the Attempt.
```text
activity transition
↓ validate
commit Attempt + Measurements
↓ publish semantic effects
overlay / narration / capture / editorial consumers
```
This is both a security rule and a product reliability rule.
---
# Design the creator timeline (/docs/creator/creator-timeline)
Emit fewer, better semantic moments that explain progress, stakes, setbacks, breakthroughs, and outcomes.
A creator timeline is not a firehose of inputs. It is an ordered set of verified
moments that help a viewer or editor understand the story.
## Three layers of fact [#three-layers-of-fact]
| Layer | Example | Typical consumer |
| ---------------------- | --------------------------------------- | ------------------------------------------- |
| Activity event | target 20 hit on dart 3 | replay/debug, detailed overlay |
| Story Event | Around the Clock completed | viewer overlay, editor timeline |
| Derived story judgment | first clean finish after three setbacks | Content Studio reasoning from several facts |
Packages should emit domain truth, not editorial speculation. The Studio can
combine committed facts, Sprint context, and research into a narrative later.
## Useful story vocabulary [#useful-story-vocabulary]
* beginning: baseline established, goal activated, route chosen;
* progress: milestone cleared, consistency improved, rank gained;
* tension: near miss, regression, lead change, failed finish;
* breakthrough: personal best, first completion, record pace;
* outcome: Sprint finish line reached, match won, attempt abandoned;
* integrity: evidence gap, correction, event retraction, manual fallback.
## Payload design [#payload-design]
Include bounded facts that explain **why** the event matters: current/previous
value, threshold, target, actor, round, route position, or rank. Avoid formatted
sentences as the only source of meaning.
```ts
{
eventType: "rank_gained",
facts: {
modeId: "around-the-clock",
previousRank: "silver",
currentRank: "gold",
qualifyingResult: 38
}
}
```
## Density discipline [#density-discipline]
If every throw or keypress becomes a high-value Story Event, the timeline is
unusable. Preserve granular activity evidence separately and emit story events
at meaningful semantic boundaries. Use priorities only to distinguish value,
not to make every event urgent.
## Correction [#correction]
When corrected evidence changes the story, emit a retraction for invalidated
events and replacement events from exact replay. Preserve the audit trail so an
editor never cuts a moment the current result disproves.
---
# Creator tooling (/docs/creator)
Use the same verified practice evidence to improve a live stream, preserve story moments, and prepare a production handoff.
Creator tooling is an optional layer on the ordinary Club loop. It does not
change whether an Attempt commits and it is not a permanent account type.
When a Sprint has creator intent, Chasing Mastery guides the member through
Station, OBS, overlay, and evidence preparation so the pursuit can become a
coherent long-form story or a stream-derived short.
## Creator evidence flow [#creator-evidence-flow]
```text
Practice Mode
→ committed Attempt
→ semantic Story Events
→ Station capture clock
→ media anchors
→ sealed creator evidence
→ immutable Content Studio intake
```
## What packages contribute [#what-packages-contribute]
* viewer-relevant Story Event vocabulary;
* a read-only activity overlay;
* presentation mapping for ready, live, stale, terminal, and replay states;
* optional coordination and narration policy;
* bounded facts explaining domain-specific stakes and outcomes.
## What Station and the host contribute [#what-station-and-the-host-contribute]
* OBS connection and scene/source verification;
* capture identity and clock samples;
* synchronization and gap detection;
* mapping committed Story Events to media windows;
* revocable overlay access;
* media/evidence integrity and retention;
* a sealed, idempotent Studio handoff.
## Live value comes first [#live-value-comes-first]
The creator layer should improve the stream even if no video is ever edited:
clear overlays, visible goals, pace and stakes, honest connection state,
meaningful narration, and eventually audience participation. The production
timeline then preserves the moments viewers already found meaningful.
---
# OBS and capture synchronization (/docs/creator/obs-and-capture)
Connect Station to a recording clock, verify presentation, and map committed facts to exact media windows without blocking practice.
Station owns OBS and capture integration. A package never receives an OBS
WebSocket password, scene list, recording path, or control command.
## Setup [#setup]
### Pair Station [#pair-station]
The member pairs a specific Station through host authorization. Pairing does not
grant an installed package native access.
### Connect OBS [#connect-obs]
Station holds the credential locally, connects to the configured OBS instance,
and exposes only bounded health to the member experience.
### Verify scene and overlay [#verify-scene-and-overlay]
The member confirms the expected scene/source and loads the revocable
package-owned read-only overlay. Verification does not start an Attempt.
### Start capture [#start-capture]
Station records capture identity, local clock, OBS time samples, scene state,
and discontinuities. Practice remains authoritative if capture fails.
### Anchor committed events [#anchor-committed-events]
After each Story Event commits, the host maps its event time to one bounded
capture window using recorded clock provenance.
## Clock model [#clock-model]
Do not assume package time, cloud receipt time, Station monotonic time, OBS
recording time, and encoded media time are identical. Store explicit samples and
mapping uncertainty so an editor can distinguish a precise moment from a wider
recovery window.
## Failure isolation [#failure-isolation]
* OBS disconnect does not abort or roll back an Attempt.
* Overlay failure does not suppress Story Events.
* Media write failure creates an evidence gap, not fabricated media.
* Station restart preserves prior committed activity and reports unsynchronized
periods explicitly.
* Revocation stops future capture/overlay access while keeping already retained
evidence provenance.
## Author responsibility [#author-responsibility]
The package supplies semantic presentation and facts. It should not compensate
for capture timing by embedding local file offsets or introducing sleeps around
activity commit.
---
# Production evidence and Studio intake (/docs/creator/production-evidence)
Seal source provenance, activity truth, Story Events, media anchors, and gaps into an immutable editorial starting point.
The Content Studio may research, reason, script, generate, compose, and publish,
but it should begin from an exact immutable intake rather than re-querying
mutable practice state throughout production.
## Intake contents [#intake-contents]
* member and Pursuit/Sprint references appropriate to the authorized project;
* exact package release and capability versions;
* Attempt/revision identities and Measurements;
* progression and finish-line evidence;
* current Story Events and explicit retractions;
* capture identities, media anchors, clock provenance, and evidence gaps;
* overlay/narration presentation references;
* checksums and sealing time;
* privacy and use constraints.
## What is deliberately absent [#what-is-deliberately-absent]
* Station credentials;
* OBS passwords;
* provider API keys;
* connector grants;
* arbitrary account history;
* mutable live activity handles;
* claims not supported by committed evidence.
## Idempotent handoff [#idempotent-handoff]
Sealing the same eligible source set with the same request identity returns the
same intake. If corrected evidence requires a new intake, preserve the relation
to the superseded one rather than mutating bytes that editorial work may already
reference.
## Package author quality bar [#package-author-quality-bar]
A sophisticated creator package should let an editor answer:
1. What was the goal?
2. What was the starting point?
3. Which moments materially changed the story?
4. What result was authoritative after correction?
5. Where is the corresponding media?
6. Which periods are missing or uncertain?
7. Which domain context will still require external research?
The package supplies trustworthy domain facts. It does not attempt to replace
editorial judgment or exhaustive topic research.
---
# Chasing Mastery Author plugin (/docs/get-started/author-plugin)
One source-owned plugin for Codex, ChatGPT, and Claude—portable packages, Station connectors, and scoped Club setup from a blank workspace.
**Chasing Mastery Author** is one plugin with three focused skills:
| Skill | Use it for |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Build a Chasing Mastery package | Experience Suites, Practice Modes, rich players, progression, Story Events, overlays, coordination, and narration |
| Build a Chasing Mastery connector | Native/local source discovery and semantic observations through Station |
| Manage Chasing Mastery Club | Pursuit discovery, Suite install, Practice Mode setup, Sprints, and owner-private package submission through scoped OAuth |
You describe the product outcome. The skill asks only the missing questions,
writes a durable authoring brief, bootstraps a standalone workspace, and drives
the project-local tools. Package and connector authoring remain separate trust
lanes even though they ship in one plugin.
## Blank-machine behavior [#blank-machine-behavior]
The package skill does not require a platform checkout or global CLI. Its
bootstrap uses exact Node `24.18.0` or installs that checksum-pinned portable
runtime in an author cache, verifies bundled toolchain digests, and creates the
project. It never uses `sudo`, a system package manager, or a global npm install.
Connector authoring needs Rust `1.95` because it produces a supervised sidecar.
The skill keeps the connector's Rust SDK, Lab, and sandbox project-local. The
public archive carries reviewed Lab/sandbox binaries for Linux x86-64 and Apple
Silicon macOS; Windows and Intel macOS are not certified connector-authoring
hosts.
## Exact release source [#exact-release-source]
The canonical plugin snapshot is `plugins/chasing-mastery-author`. Its
`.codex-plugin/plugin.json` describes the single plugin, `release.json` pins the
payload digest and file count, and each skill contains its own references,
fixtures, scripts, and toolchain assets. The docs build verifies those files and
the release record rather than copying a second authoring specification.
Developer Preview 0.2.0 is publicly downloadable with exact release metadata.
Claude Code has a checksum-pinned HTTPS marketplace, Codex has a verified local
marketplace bundle, and eligible ChatGPT plans can upload either focused local
authoring skill. The OpenAI universal-directory listing is submission-ready but
truthfully remains unavailable until the production MCP resource and external
review are complete. Follow [Build with your agent](./build-with-an-agent) for
the current supported path instead of guessing an install command.
## What the plugin will never request [#what-the-plugin-will-never-request]
* a Chasing Mastery password or browser session;
* an API, store, publisher, Station, or provider secret in a prompt;
* direct database or account storage access;
* arbitrary filesystem/network/native authority for a portable package;
* permission to publish merely because local conformance passed.
Club setup uses first-party OAuth consent with separate `club.read`,
`club.manage`, and `packages.submit` scopes. Package authoring itself remains
local until the member explicitly asks to submit exact review bytes.
Use the Chasing Mastery Author plugin to build a new Experience Suite. Interview
me for the member promise, modes, Attempt boundaries, inputs, Measurements,
progression, player, overlay, Story Events, corrections, coordination,
narration, and acceptance scenarios. Write the authoring brief, bootstrap the
standalone project, implement against public SDKs, and open the real Workbench.
Do not prepare release bytes until I approve the experience and conformance
passes.
---
# The authoring workflow (/docs/get-started/authoring-workflow)
The complete local loop from product idea to immutable review handoff.
## The loop [#the-loop]
```text
idea
→ authoring interview
→ standalone project
→ fixtures + implementation
→ Workbench / Connector Lab
→ conformance
→ immutable archive + digest
→ private review
→ owner-only install
→ later compatible release
```
## Package project [#package-project]
The Author plugin creates a directory shaped like this:
```text
my-experience/
├── chasing-mastery.authoring.json
├── chasing-mastery.package.json
├── chasing-mastery.listing.json
├── package.json
├── src/
├── fixtures/
└── .chasing-mastery/
├── run.sh
├── run.ps1
├── toolchain.json
└── toolchain/
```
The `.chasing-mastery` directory is project-local infrastructure. Authors use
its scripts through ordinary package commands; they do not install or maintain
a global Chasing Mastery CLI.
## Commands [#commands]
| Command | Purpose |
| ----------------------------------------------- | -------------------------------------------------- |
| `npm run cm -- status` | explain the project and missing proof |
| `npm run cm -- workbench` | open the real package artifacts and fixtures |
| `npm run cm -- conformance` | validate schemas, behavior, authority, and claims |
| `npm run cm -- ready` | produce deterministic archive, digest, and handoff |
| `npm run cm -- evolution --from previous.cmpkg` | classify compatibility against exact prior bytes |
The precise scripts can vary with the scaffolded project, but every operation
resolves through its pinned local toolchain.
## Proof is product work [#proof-is-product-work]
Fixtures are not test debris. They explain the contract:
* the normal completion path;
* every meaningful terminal result;
* malformed or unauthorized input;
* repeated/delayed intent and idempotency;
* stale connection and recovery;
* reduced motion and multiple viewports;
* manual and automatic equivalence;
* progression boundary values;
* correction and retraction when supported;
* coordination or narration edge cases when declared.
Workbench should show the same thing a member or viewer will see while driving
the actual immutable code—not a second author-only renderer.
## Review is independent [#review-is-independent]
`ready` means **ready for review**, not approved or publicly listed. The host
replays the archive in isolation, verifies its digest and declared capabilities,
and creates an owner-private listing only after review succeeds. Public
community publication remains a separate moderated operation.
---
# Build with your agent (/docs/get-started/build-with-an-agent)
Install one source-owned Chasing Mastery authoring workflow in Codex, ChatGPT, or Claude and take an idea to the real Workbench.
You should not need to learn Chasing Mastery infrastructure before you can test
a good practice idea. Choose the coding agent you already use, describe the
member experience in ordinary language, and let the **Chasing Mastery Author**
workflow handle the brief, standalone project, pinned tools, preview, proof, and
review handoff.
All three routes use the same Agent Skills, version-3 package brief, public SDK,
Workbench, Connector Lab, and immutable release format. The invocation syntax
changes; the authored project does not. You can start in one provider and
continue in another without migration or regenerated source.
> **Current channel: Developer Preview 0.2.0.** Local package and connector
> authoring is real and credential-free. Optional Club tools currently use the
> clearly labeled staging OAuth/MCP resource. The OpenAI universal-directory
> listing is prepared but cannot be published until production MCP deployment
> and external review are complete.
## Certified hosts [#certified-hosts]
The exact public archive—not a source checkout—has completed both the complete
Experience Suite/Workbench journey and the Station connector/Connector Lab
journey on:
* Linux x86-64;
* Apple Silicon macOS.
Read the [release-bound certification record](https://docs.chasingmastery.club/downloads/chasing-mastery-author/0.2.0/certification.json)
or follow `certification.report` from the latest release JSON. Windows remains
**uncertified preview-only**. The package bootstrap contains a PowerShell path,
but that is not equivalent to a passing Windows machine journey. Connector
authoring does not support Windows or Intel macOS in this release.
## Codex [#codex]
The public preview is a downloaded local marketplace. It works in Codex today
without access to the private platform repository.
### Download and verify the exact marketplace [#download-and-verify-the-exact-marketplace]
Download the [Codex preview bundle](https://docs.chasingmastery.club/downloads/chasing-mastery-author/0.2.0/chasing-mastery-author-openai-preview-0.2.0.zip)
and its [release record](https://docs.chasingmastery.club/downloads/chasing-mastery-author/latest.json). Compare
the archive's SHA-256 with `providers.openai.codexDeveloperPreview.sha256` before
extracting it.
```bash
shasum -a 256 chasing-mastery-author-openai-preview-0.2.0.zip
```
On Linux, use `sha256sum` instead. A mismatch means stop; do not install or ask
an agent to work around it.
### Add the extracted marketplace [#add-the-extracted-marketplace]
```bash
unzip chasing-mastery-author-openai-preview-0.2.0.zip
codex plugin marketplace add ./chasing-mastery-developers
codex plugin add chasing-mastery-author@chasing-mastery-developers
```
Start a **new Codex thread** after installation so the thread receives the new
skill catalog.
### Ask for the outcome [#ask-for-the-outcome]
```text
Use $build-chasing-mastery-package to build a practice experience for the goal
below. Interview me only for choices that materially affect the member
experience, then open the real result in Workbench.
[Describe the pursuit, one Attempt, the result, and the ideal player experience.]
```
After OpenAI review and publication, the same plugin will be installable from
the universal Plugins Directory shared by ChatGPT and Codex. That future route
replaces the preview download; it does not introduce a second workflow.
## ChatGPT [#chatgpt]
Eligible ChatGPT plans can upload either local authoring skill now from
**Plugins → Skills → Create → Upload from your computer**:
* [Build a package skill](https://docs.chasingmastery.club/downloads/chasing-mastery-author/0.2.0/build-chasing-mastery-package-0.2.0.zip)
* [Build a connector skill](https://docs.chasingmastery.club/downloads/chasing-mastery-author/0.2.0/build-chasing-mastery-connector-0.2.0.zip)
Review the downloaded archive and compare its SHA-256 with the corresponding
entry under `providers.openai.chatgptPersonalSkills.downloads` in the
[release record](https://docs.chasingmastery.club/downloads/chasing-mastery-author/latest.json) before upload.
Open ChatGPT Work on an empty local folder, invoke the installed skill, and use
the same product prompt shown above.
This early-access route uploads one focused skill at a time. It does not add the
scoped Club MCP tools. The reviewed universal plugin is the intended complete
ChatGPT experience; until it is published, the docs will not imply that a
directory install or authenticated Club handoff already exists.
## Claude Code [#claude-code]
Claude Code 2.1.224 or newer can install the checksum-pinned archive directly
from the Chasing Mastery marketplace:
```bash
claude --version
claude plugin marketplace add https://docs.chasingmastery.club/integrations/claude/marketplace.json
claude plugin install chasing-mastery-author@chasing-mastery-developers
```
Restart Claude Code or run `/reload-plugins`, then invoke:
```text
/chasing-mastery-author:build-chasing-mastery-package
```
Natural language also works: “Build a Chasing Mastery Practice Mode for this
goal.” The explicit command is useful when you want to make the workflow choice
unambiguous.
Claude verifies the archive against the SHA-256 pin in the marketplace. A
failed integrity check is terminal; never disable verification or replace the
archive with an unpinned copy.
## What the agent should do next [#what-the-agent-should-do-next]
The first interaction should feel like product design, not environment setup:
1. recognize whether the idea needs a package, a connector, or both;
2. ask one compact batch of only the unanswered product questions;
3. restate the member promise, Attempt, result, progression, player, creator
presentation, correction policy, and edge cases;
4. write the provider-neutral authoring brief;
5. bootstrap the standalone project without `sudo`, a global CM CLI, or a
platform checkout;
6. implement against public SDKs and open the real artifact in Workbench or
Connector Lab;
7. iterate visibly until you approve the experience;
8. produce immutable review bytes only after conformance passes and you say it
is ready.
The bootstrap uses exact Node `24.18.0`. If the host has a different version,
it downloads the platform's checksum-pinned portable runtime into the author
cache; it never replaces or globally upgrades the developer's Node installation.
Continue with [the complete authoring workflow](./authoring-workflow) to see the
project that remains after the conversation ends.
## Sign-in is intentionally late [#sign-in-is-intentionally-late]
Designing, running, and packing an experience is local. No Chasing Mastery
account is required. Sign-in begins only if you explicitly ask the agent to
search your Club, submit exact private package bytes, or set up a Pursuit and
Sprint. That action must open first-party OAuth consent with only the necessary
`club.read`, `club.manage`, or `packages.submit` scopes.
Never paste a password, cookie, access token, publisher key, Station credential,
or billing secret into the conversation. The plugin does not need one.
## Updates and rollback [#updates-and-rollback]
* **Codex preview:** download the new semantic-version bundle, verify its release
record, add or refresh that marketplace, and reinstall the plugin. Start a new
thread.
* **Claude:** run `claude plugin marketplace update chasing-mastery-developers`,
then reinstall when the marketplace advertises a new plugin version.
* **Rollback:** use a retained versioned archive and release record. Never
overwrite old bytes under the same semantic version.
The [latest release record](https://docs.chasingmastery.club/downloads/chasing-mastery-author/latest.json) is the
machine-readable source of version, payload, archive, provider, support, and MCP
channel truth.
---
# Choose the correct artifact (/docs/get-started/choose-an-artifact)
Put each concern in the public component that can own it safely and portably.
| Need | Build | Owns | Never owns |
| ------------------------------------------ | ------------------------- | ----------------------------------------------- | ------------------------------------- |
| Rules, scoring, state, result | Package activity | deterministic Attempt behavior | identity, persistence, clock, network |
| A board, puzzle, timer, or spatial control | `web_ui` artifact | presentation and typed intents | canonical mutation, native access |
| Stream presentation | `overlay_ui` artifact | read-only visuals | OBS control, tokens, history queries |
| Ranks and milestones | progression contribution | metric, aggregation, thresholds | Attempt truth |
| Editing-worthy facts | story contribution | semantic vocabulary | recording or media storage |
| Matches or races | coordination contribution | roster policy, arbitration, outcomes | invites, connections, sequencing |
| Commentary | narration contribution | fact-to-cue policy | provider keys, synthesis, playback |
| Shared vertical rules or UI | Domain Kit | pure build-time code and assets | runtime service or installation |
| Automatic source input | Station connector | discovery, translation, stable event ID, health | rules, member routing, Sprint choice |
| Club setup by an agent | HTTP API or MCP | bounded ordinary member operations | attempts, billing, connector grants |
## Common wrong turns [#common-wrong-turns]
A sidecar receives a stricter independent review because it may need narrow
local authority. Packaging it together does not make that authority safe.
The connector should report “segment 20, multiplier 3” or another exact
observation. The active Practice Mode decides whether that is a hit, miss,
checkout, invalid action, or ignored event.
A narration contribution proposes bounded provider-neutral cues from
committed facts. The host owns voices, credentials, queues, synthesis,
playback, caching, and recovery.
## Decision test [#decision-test]
Ask: **would changing this behavior change what the Attempt means?** If yes,
it probably belongs in immutable package bytes. Ask: **does it require trust in
an account, clock, device, credential, connection, or durable store?** If yes,
it belongs in a host service or separately reviewed connector—not the package.
---
# Start building (/docs/get-started)
Go from a plain-language practice idea to a real package or connector without learning the entire platform first.
You do not need the Chasing Mastery repository, a global CLI, or private host
access to author an extension. Start by choosing whether you are defining
**meaning** or observing an **external source**.
## Package or connector? [#package-or-connector]
| Your sentence begins with… | Build | Example |
| ---------------------------------- | ----------------- | ---------------------------------------------- |
| “One Attempt should…” | Package activity | score a timed puzzle rush |
| “The result should contain…” | Package activity | accuracy, duration, and streak |
| “The member should interact with…” | Package player | chess board, dart board, split controls |
| “The stream should show…” | Package overlay | target, pace, rank, current route |
| “When the game/device/tool emits…” | Station connector | AutoDarts throw, LiveSplit split, browser move |
| “Several modes together should…” | Experience Suite | complete Darts or Chess practice offering |
Most automatic experiences use both artifacts. Design them together, but keep
them independently reviewed. The compatibility seam is an exact observation
type, contract version, canonical payload schema, and schema digest.
## Recommended path [#recommended-path]
### Describe the experience to your coding agent [#describe-the-experience-to-your-coding-agent]
Choose [Codex, ChatGPT, or Claude](./build-with-an-agent), install the single
**Chasing Mastery Author** workflow, then ask it to build a package or
connector. It will interview you about the Attempt boundary,
Measurements, evidence, progression, presentation, and failure states before
writing code.
### Let the plugin scaffold a standalone project [#let-the-plugin-scaffold-a-standalone-project]
The generated directory includes source, fixtures, the authoring brief, pinned
toolchain archives, and project-local POSIX and Windows launchers. Everything
needed to exercise the extension travels with the project.
### Iterate in Workbench or Connector Lab [#iterate-in-workbench-or-connector-lab]
Workbench is the real package host for authoring. Connector Lab is the real
zero-grant native harness. Neither is a screenshot mock or a separate
simulation model.
### Ask for `ready` [#ask-for-ready]
The local toolchain validates design metadata, executes fixtures, checks
conformance, packs immutable bytes, and writes a review handoff. Failed proof
does not produce a releasable package.
```text
Build a Chasing Mastery Practice Mode for [pursuit]. One Attempt begins when
[start] and ends when [terminal condition]. The member can [inputs]. Record
[measurements]. The primary comparable result is [metric and direction]. I want
[progression], [story moments], [player UI], and [overlay]. Automatic evidence
will eventually come from [source], but keep manual input fully usable.
Use only public Chasing Mastery SDKs and the project-local authoring toolchain.
Open the real result in Workbench, exercise important edge cases, and do not
prepare a release until conformance passes.
```
## Before you write code [#before-you-write-code]
Read the [five-minute mental model](./mental-model) and
[choose the correct artifact](./choose-an-artifact). Those two pages prevent the
most expensive architectural mistakes: putting scoring in a connector, giving
an overlay authority, inventing an enclosing practice session, or making
historical results incomparable through a later release.
---
# The five-minute mental model (/docs/get-started/mental-model)
Pursuits, Sprints, Experience Suites, Practice Modes, Attempts, evidence, and story—without overlapping vocabulary.
## Product objects [#product-objects]
### Pursuit [#pursuit]
A **Pursuit** is a shared community and domain: Darts, Chess, Memory Training,
Geometry Dash, or another coherent thing people pursue. It is not one member's
goal or a folder of content.
### Sprint [#sprint]
A **Sprint** is one member's focused goal inside a Pursuit. It may be the next
short-term goal in lifelong mastery or the entire story for a creator's
one-off challenge. A Sprint references a Practice Mode and a verifiable finish
line; ordinary practice does not require one.
### Experience Suite [#experience-suite]
An **Experience Suite** is a member-facing convention for a coherent collection
of Practice Modes and creator presentation. It is delivered by a Library
listing and one primary immutable package release. It is not another persisted
aggregate or install wizard.
### Practice Mode [#practice-mode]
A **Practice Mode** is a reusable protocol that knows how one kind of practice
works. Around the Clock, Puzzle Rush, a split segment drill, and a reaction-time
test are Practice Modes.
### Attempt [#attempt]
An **Attempt** is one atomic execution of a Practice Mode. A completed Attempt
is terminal by itself. Never create a hidden requirement to stop a board,
session, or practice container after it completes.
### Measurement and progression [#measurement-and-progression]
A **Measurement** is one typed result from an Attempt. An immutable
**Progression Definition** maps comparable evidence to a rank ladder. The
member's current progression projection can be rebuilt; the Attempts remain
the source of truth.
### Story Event [#story-event]
A **Story Event** is a verified semantic fact emitted after activity commit:
personal best, rank gained, target cleared, comeback begun, or match won.
Overlays, narration, capture anchoring, and Content Studio consume these facts
without gaining gameplay authority.
## Execution model [#execution-model]
```text
Package release (immutable)
activity description
↓
initialize Attempt
↓
command or exact observation
↓
deterministic transition
├─ next package state
├─ Measurements
├─ terminal outcome
└─ semantic effects
↓ commit first
Story Events / overlay / narration / media anchors
```
Derived consumers may fail without losing the authoritative Attempt. Package
execution never waits for an overlay, audio provider, recorder, editorial job,
or another non-authoritative consumer.
## Two input paths, one rule path [#two-input-paths-one-rule-path]
Manual and automatic input should converge before domain logic:
```text
portable player command ─────┐
├─ normalized package action → reducer
Station exact observation ───┘
```
If both represent the same real action, they must create the same state,
Measurements, completion, progression evidence, Story Events, and presentation.
## Package, Domain Kit, connector [#package-domain-kit-connector]
| Artifact | When it exists | Authority |
| ---------- | -------------------------------------- | --------------------------------------- |
| Package | installed immutable runtime experience | deterministic package boundary only |
| Domain Kit | compiled into a package at build time | none; pure rules, schemas, UI, fixtures |
| Connector | separately approved local sidecar | exact narrow grants supplied by Station |
A Chess Domain Kit might contain board rules and reusable components. A Chess
package uses it to build Puzzle Rush. A browser connector observes Chess.com.
The member installs the Chess Experience Suite, not a generic kit and a pile of
configuration.
---
# Source binding and live verification (/docs/connectors/binding-and-verification)
Let a member choose the right automatic source, prove that it is live, and route it without creating fake practice history.
A connector can discover several sources. A package can accept several
observation contracts. Neither fact identifies which source should control one
member's Practice Mode.
The host owns a **source binding** that joins:
* Station and connector installation;
* discovered source identity;
* exact observation contract;
* Pursuit and Practice Mode configuration;
* member-granted input route;
* verification and health state.
## Setup flow [#setup-flow]
### Discover [#discover]
Station displays sources reported by the reviewed connector using safe labels
and health. The package listing explains why the source is useful.
### Select [#select]
The member chooses a source for the ready Practice Mode. The host checks exact
contract compatibility and required connector grants.
### Verify live input [#verify-live-input]
The member performs one harmless recognizable action. Station observes and
validates it through a verification route that cannot commit an Attempt,
Measurement, progression, Story Event, or Sprint evidence.
### Bind [#bind]
After explicit confirmation, the host creates a revocable route. Future live
Runs may use it, but merely binding a source does not begin practice.
### Monitor [#monitor]
The player and Station show healthy, stale, reconnecting, unavailable, or
revoked state. Manual fallback remains available when the package supports it.
## Why verification is not practice [#why-verification-is-not-practice]
Testing a dart throw, timer split, or browser move during setup should not create
a fake personal best, history row, rank change, or creator moment. Verification
is host-owned source proof with a separate route and retention policy.
## Revocation [#revocation]
Removing a binding prevents new routes immediately. Revoking the connector grant
also closes the underlying source. Previously committed Attempts retain their
provenance without preserving live connector authority.
---
# Connector Lab (/docs/connectors/connector-lab)
Exercise real connector bytes, grants, protocol messages, health, failure recovery, and package compatibility before review.
Connector Lab is the native development harness shipped with the standalone
connector project. It launches the actual sidecar under the real supervisor and
sandbox boundary.
## What it proves [#what-it-proves]
* valid handshake and identity;
* rejection of malformed or oversized messages;
* requested capabilities match the authoring brief;
* configuration and source discovery;
* start, health, observation, stop, and shutdown lifecycle;
* stable event identity across replay and restart;
* reconnect/backoff behavior;
* prompt termination after revocation;
* bounded redacted diagnostics;
* exact observation compatibility with a target package.
## Deterministic fixture mode [#deterministic-fixture-mode]
Every connector should have a deterministic fixture source that produces the
same raw source sequence without a real account, game, or device. Fixture mode
is how CI and independent review reproduce behavior.
It must pass through the same translation code as the live source. Do not make a
second “test observation” implementation that bypasses parsing, identity, or
health behavior.
## Workbench loopback [#workbench-loopback]
Connector Lab can forward emitted observations into the real Workbench activity
runtime. The combined journey proves:
```text
raw fixture
→ real connector translator
→ real supervisor/sandbox
→ exact observation envelope
→ real package reducer
→ terminal Attempt result
```
This is stronger than validating the connector and package against two unrelated
sample files.
## Review handoff [#review-handoff]
The connector skill produces binary digest, platform/architecture, protocol and
SDK versions, requested capabilities, fixture digest, lifecycle evidence,
sandbox results, diagnostics summary, and known limitations. It does not sign
or publicly approve its own binary.
---
# Health and recovery (/docs/connectors/health-and-recovery)
Keep automatic evidence understandable through startup, stale sources, reconnect, duplicates, gaps, and restart.
Automatic input is only magical when failure is legible. A player should never
quietly stop updating while implying that evidence is healthy.
## Health states [#health-states]
| State | Meaning | Member presentation |
| ------------ | ---------------------------------------- | ---------------------------------------- |
| starting | process/source opening | brief bounded preparation state |
| ready | source live and observations current | automatic input ready |
| degraded | usable with known limitation | explain limitation and fallback |
| reconnecting | source interrupted; retry in progress | retain last committed truth, show stale |
| failed | retry exhausted or configuration invalid | actionable recovery, manual fallback |
| revoked | authority removed | source stopped; reauthorization required |
## Recovery requirements [#recovery-requirements]
* Backoff is bounded and observable.
* Reconnect does not mint new identity for replayed upstream events.
* Duplicate observations remain harmless.
* Sequence gaps become explicit diagnostics and creator evidence gaps.
* Station process restart can reconcile connector state and active routes.
* Package UI requests an authoritative snapshot on foreground/reconnect.
* Committed Attempts never depend on the connector remaining installed.
## Exactly-once effect, not delivery fantasy [#exactly-once-effect-not-delivery-fantasy]
Networks and processes can deliver at least once. Stable observation identity,
host deduplication, expected activity revision, and package determinism create an
exactly-once authoritative effect for one event.
## Diagnostics [#diagnostics]
Expose connector state, safe source label, last healthy timestamp, retry count,
protocol errors, gap/dedup counters, and capability state. Keep raw sensitive
payloads, tokens, file contents, and member identity out of ordinary logs and
support exports.
---
# Station connectors (/docs/connectors)
Translate a local device, game, browser, specialist tool, file, or service into exact semantic observations through a separately reviewed sidecar.
Station is Chasing Mastery's local eyes and ears. A connector discovers and
observes one external source, normalizes source-specific data, emits stable exact
observations, and reports health. It does not know the active member goal or
score the Practice Mode.
```text
AutoDarts / LiveSplit / game log / browser / tool
↓
Station connector sidecar
↓ exact observation
host-owned source binding + route
↓
package-owned Practice Mode reducer
```
## Why connectors are separate [#why-connectors-are-separate]
Portable packages are zero-authority deterministic code. A connector may need
narrow native access—a specific private-LAN endpoint, reviewed file path, or
supervised process interaction—so it must be installed, granted, monitored, and
revoked independently.
An Experience Suite may recommend a connector, but package and connector bytes
never become one trust decision.
## Connector responsibilities [#connector-responsibilities]
* advertise exact protocol identity and supported source kind;
* discover or accept a bounded source configuration;
* translate raw events into a canonical payload schema;
* create stable source-event identity for replay and deduplication;
* report startup, ready, degraded, reconnecting, and stopped health;
* tolerate source interruption and process restart;
* honor grant revocation promptly;
* produce diagnostic evidence without leaking payloads or credentials.
## Start here [#start-here]
## Supported authoring host [#supported-authoring-host]
The standalone connector skill carries the public Rust SDK plus reviewed
Connector Lab and sandbox binaries for Linux x86-64 and Apple Silicon macOS.
The exact hosted archive has passed clean extraction, bootstrap, real fixture
replay, deterministic duplicate receipt, terminal shutdown, packing, and
immutable handoff on both hosts. Windows and Intel macOS are unsupported for
connector authoring today. Broader public signing and platform distribution
remain gated; do not claim an unreviewed connector can be installed by the
community merely because it passes local fixtures.
---
# Exact observation contracts (/docs/connectors/observations)
Make independently released package and connector bytes agree on meaning, schema, version, and identity.
An observation contract is more than an event name. Compatibility requires the
complete tuple:
```text
observation type
+ positive contract version
+ RFC 8785 canonical payload schema
+ SHA-256 digest of canonical schema bytes plus newline
```
The package owns the semantic payload schema because the package owns meaning.
The connector declares that exact reviewed contract because it promises to emit
matching evidence.
## Example [#example]
```json
{
"type": "darts.autodarts.throw",
"contractVersion": 1,
"payloadSchemaSha256": "…",
"payload": {
"segment": 20,
"multiplier": 3
}
}
```
`bull` and `outer_bull` are domain observations, not invalid segment numbers.
The active mode decides whether they score, advance a target, or count as a
miss. That interpretation cannot live in the AutoDarts connector.
## Stable source-event identity [#stable-source-event-identity]
The connector derives an event key from stable source facts whenever possible:
source ID, upstream sequence, round/visit key, and event index. Reconnect and
replay of the same upstream event must produce the same identity.
Do not use local arrival time or a random UUID when the source provides stable
identity. The host deduplicates before authoritative transition application.
## Canonical schema [#canonical-schema]
Packing canonicalizes JSON Schema with RFC 8785, appends one newline, and hashes
those bytes. This removes whitespace and object-key-order ambiguity while
making any meaningful schema change explicit.
Structurally similar payloads with different schema digests are intentionally
incompatible. Publish a new contract version and coordinate package/connector
support rather than guessing across versions.
## Bound the payload [#bound-the-payload]
Use the narrowest semantic facts the Practice Mode needs. Avoid raw video,
screenshots, unbounded logs, arbitrary nested metadata, provider credentials,
or entire upstream responses. High-frequency telemetry should remain local;
emit bounded domain observations.
---
# Connector protocol and lifecycle (/docs/connectors/protocol)
Build a supervised zero-grant sidecar with bounded messages, explicit capabilities, health, and graceful recovery.
## Process model [#process-model]
Station launches the connector as a child process with a controlled environment
and line-delimited protocol. The sidecar begins without account, package,
Attempt, Sprint, Station-store, OBS, or arbitrary host authority.
## Lifecycle [#lifecycle]
### Handshake [#handshake]
The sidecar reports protocol version, connector identity/version, supported
observation contracts, requested capability classes, and implementation
metadata. Station rejects unsupported or contradictory declarations.
### Configure [#configure]
Station supplies only reviewed source configuration and opaque grant references.
The connector validates before opening a source.
### Start [#start]
The sidecar opens exactly the granted source and reports transition through
starting to ready or degraded health.
### Observe [#observe]
Each source event becomes one bounded observation with stable identity,
canonical payload, source timestamp when available, and connector provenance.
### Stop [#stop]
Stop closes the source and returns to a configured state without losing process
protocol integrity.
### Shutdown [#shutdown]
Shutdown releases every resource and exits. Station treats refusal or timeout
as a supervised process failure and terminates it.
## Message discipline [#message-discipline]
* Parse every inbound message through the public SDK.
* Emit only bounded protocol messages on stdout.
* Write human diagnostics to the designated diagnostic channel, never mixed
into protocol output.
* Never log credentials, authorization headers, complete sensitive payloads, or
account identity.
* Treat unknown message types and versions as errors, not forward-compatible
guesses.
* Use stable codes and safe summaries for health/diagnostics.
## No hidden routing [#no-hidden-routing]
The sidecar does not receive a member ID, Sprint ID, or active Practice Mode.
Station and the host bind a discovered source to an authorized input route after
compatibility and live verification succeed.
---
# Connector security and review (/docs/connectors/security)
Request the narrowest local authority, prove it under supervision, and keep native code independent from package publication.
Native connector code is not portable package code. Passing package conformance
does not approve a connector, and approving a connector does not approve every
package that accepts its observations.
## Zero-grant default [#zero-grant-default]
The sidecar begins with no arbitrary network, filesystem, process, credential,
account, Station-store, OBS, or package authority. Declare every capability in
the authoring brief and test behavior without it.
Examples of narrow reviewed grants:
* connect to one configured private-LAN host and port;
* read one user-selected file tree with constrained extensions;
* communicate with one supervised local socket;
* store connector-local opaque state in a bounded host-provided location.
## Review questions [#review-questions]
1. Can the same outcome be achieved with less authority?
2. Is source configuration bounded and validated?
3. Are credentials held by Station rather than exposed to package code?
4. Does revocation close every resource promptly?
5. Can deterministic fixtures reproduce translation and failure behavior?
6. Are observations narrow, semantic, versioned, and size bounded?
7. Are logs and diagnostics safe to retain and share?
8. Does the connector avoid anti-cheat-sensitive memory reading or injection?
Supported APIs, files, logs, replays, save files, official plugins, and
explicitly reviewed capture-based recognition are preferred. Direct memory
reading, injection, or anti-cheat-sensitive access is never the default launch
plan.
## Publication status [#publication-status]
The current public tooling prepares Linux x86-64 or Apple Silicon macOS
connector evidence for private review. Windows and Intel macOS are unsupported
authoring hosts. Open community signing, broad platform distribution, and
arbitrary native capability approval remain gated. Document the limitation
honestly in the Library listing.
---
# Activity engine (/docs/packages/activity-engine)
Define deterministic Attempt behavior with describe, initialize, and apply.
An activity engine is a pure reducer around one Practice Mode. It receives
validated configuration, a host-supplied run context, current package state,
and one typed input. It returns replacement state and a validated transition.
## Public interface [#public-interface]
Wrap the implementation with defineActivityEngine
so every direct call validates the same contracts the runtime validates.
```ts
import { defineActivityEngine } from "@chasingmastery/sdk";
type State = {
index: number;
hits: number;
complete: boolean;
};
export const engine = defineActivityEngine({
describe(configuration) {
return describeMode(configuration);
},
initialize(context) {
return {
state: { index: 0, hits: 0, complete: false },
status: "active",
effects: [],
};
},
apply(context, state, input) {
const action = normalizeInput(input);
return reduceAction(context, state, action);
},
});
```
## Describe before execution [#describe-before-execution]
`describe(configuration)` declares what the configured mode means:
* accepted commands and exact observations;
* available Measurements and primary result contract;
* whether lower or higher is better;
* correction support;
* player, overlay, progression, Story Event, coordination, or narration links;
* limits the host needs before starting a run.
Description is pure. It cannot inspect a member, read history, fetch a service,
or create an Attempt.
## Initialize with host context [#initialize-with-host-context]
The run context contains pinned package/release identity, host-issued run and
actor context, trusted timing information, and validated configuration. Treat
it as input, not authority you can retain outside the transition.
Return all initial package state explicitly. Do not rely on module globals,
randomness, wall-clock reads, environment variables, or request ordering.
## Apply one typed input [#apply-one-typed-input]
Normalize commands and observations into a package-owned action before domain
logic. The reducer should then be oblivious to whether a human tapped the rich
player or Station observed the same event automatically.
```ts
function normalizeInput(input: ActivityInput): DomainAction {
if (input.kind === "command") return commandToAction(input.command);
return observationToAction(input.observation);
}
```
Return a terminal transition exactly once. The host protects revision and
idempotency, but the engine should also make terminal state explicit and reject
or ignore invalid post-terminal domain actions consistently.
## Worker adapter [#worker-adapter]
createActivityWorkerHandler exposes the engine
through the isolated runtime invocation protocol. It validates contribution
identity, pinned package context, operation shape, transitions, and safe error
responses. Package code should not build a custom HTTP protocol around the
engine.
## Determinism checklist [#determinism-checklist]
* Same context, state, and input produce the same transition.
* No direct clock, random, network, filesystem, or persistent storage reads.
* Every state field is JSON-safe and schema bounded.
* Invalid inputs fail without partially mutating state.
* Effects describe intent; they do not execute host operations.
* Terminal completion needs no later Stop or End command.
---
# Package anatomy (/docs/packages/anatomy)
Understand immutable release bytes, contributions, artifacts, authoring metadata, and member-facing listing promises.
## Three descriptions, three audiences [#three-descriptions-three-audiences]
| File | Audience | Authority |
| -------------------------------- | ---------------------- | ----------------------------------------------------------- |
| `chasing-mastery.package.json` | runtime and review | executable contributions, artifacts, schemas, capabilities |
| `chasing-mastery.listing.json` | member Library | promise, screenshots, modes, input/support state |
| `chasing-mastery.authoring.json` | Workbench and reviewer | fixtures, viewport stories, design intent, release evidence |
The listing is not executable. The authoring brief is not runtime authority.
The package manifest is parsed into a strict versioned contract before any
artifact can run.
## Typical project [#typical-project]
```text
vertical-experience/
├── chasing-mastery.package.json
├── chasing-mastery.listing.json
├── chasing-mastery.authoring.json
├── src/
│ ├── package.ts
│ ├── engine.ts
│ ├── ui.ts
│ ├── presentation.ts
│ ├── overlay.ts
│ ├── coordination.ts
│ └── narration.ts
├── fixtures/
└── .chasing-mastery/
```
## Contributions point to artifacts [#contributions-point-to-artifacts]
An activity contribution identifies its configuration schema, result contract,
accepted commands and observations, worker artifact, optional player artifact,
progression, Story Events, and correction policy. Coordination and narration
are separate contributions because they answer separate policy questions.
Artifacts are content-addressed release files. A contribution refers to an
artifact by ID; the release index resolves the exact bytes. The host never
imports an author's source tree at runtime.
## Default Experience Suite [#default-experience-suite]
The package authoring brief declares:
* which mode is featured;
* the member-facing display order;
* one immutable default configuration for every mode;
* why each mode belongs in the Suite;
* which input options and creator surfaces are honestly supported.
Package defaults should make the intended experience work immediately. A member
does not configure scoring rules or thresholds that would fragment progression.
Advanced custom modes are a separate explicit workflow.
## Exact public example [#exact-public-example]
## Manifest reference [#manifest-reference]
The exact package schema is exported by `@chasingmastery/contracts`. Use the
[contract reference](/docs/reference/package-manifest) rather than copying a manifest
from a different vertical and guessing which fields are meaningful.
---
# Coordination and multiplayer (/docs/packages/coordination)
Add deterministic match, race, roster, round, and input-arbitration policy without creating a privileged multiplayer activity fork.
Coordination is policy beside an activity. The activity still owns scoring and
state transitions. The trusted host owns invitations, authenticated rosters,
connections, sequenced signals, retries, presence, and recovery.
## Public interface [#public-interface]
Wrap it with defineCoordinationEngine and expose
it with createCoordinationWorkerHandler.
## What policy may decide [#what-policy-may-decide]
* roster eligibility and readiness;
* active actor or simultaneous input topology;
* round/leg/set transitions;
* invalid or out-of-turn input handling;
* rematch eligibility;
* semantic match outcomes and Story Events.
## What the host still owns [#what-the-host-still-owns]
* finding and inviting members;
* authorization and private visibility;
* ordering signals exactly once;
* network transport and reconnect;
* assigning input routes and Station bindings;
* starting, pausing, recovering, or expiring the ephemeral Live Run.
A **Live Run** coordinates one solo activity or multiplayer match. It is not an
enclosing practice session and does not become practice-history truth.
## Topologies [#topologies]
### Shared physical source [#shared-physical-source]
Two Darts players alternate on one board. The coordination policy chooses the
active participant. Station routes the same source to the Live Run, and the
host attributes accepted input according to authenticated turn policy.
### Independent sources [#independent-sources]
Two runners or puzzle players produce evidence from separate devices. The
policy accepts simultaneous or phase-specific progress and declares outcomes
without one package connecting directly to the other.
## Required scenarios [#required-scenarios]
Prove invite/accept, readiness, ineligible roster, turn or phase arbitration,
disconnect/reconnect, completion, correction after provisional result, rematch,
duplicate signal, and deterministic recovery from the same sequenced log.
---
# Correction and exact replay (/docs/packages/corrections)
Repair committed evidence without mutating history, duplicating logic, or granting replay new authority.
Pre-terminal undo may be an ordinary package command. Repairing an already
committed Attempt is different: it crosses a host-owned correction protocol.
## Declare correction support [#declare-correction-support]
The package declares a bounded correction schema and terminal policy. A player
may send a typed correction intent; the host verifies actor authority, revision,
idempotency, package support, and policy before replaying.
## Immutable revision flow [#immutable-revision-flow]
```text
Attempt revision 1
+ authorized correction intent
+ exact pinned release bytes
↓ deterministic replay
Attempt revision 2
+ rebuilt Measurements/progression
+ Story Event additions/retractions
```
Both revisions remain inspectable. Derived projections point at the current
authorized revision.
## Replay has fewer capabilities [#replay-has-fewer-capabilities]
A historical replay can render the pinned package player against exact recorded
state, but it receives no command or correction capability. “Read-only” is
enforced by the host bridge rather than entrusted to a disabled-looking button.
## Idempotency and conflicts [#idempotency-and-conflicts]
* Repeating the same correction request returns the same result.
* A correction against an old expected revision fails visibly.
* Concurrent corrections cannot silently overwrite each other.
* Rebuild failure preserves the prior current revision.
* Story retractions are tied to the corrected source evidence.
## Darts example [#darts-example]
A member may change a wrongly detected `single 20` to `bull` after completion.
The package replays the exact throw sequence with the replacement. Around the
Clock interprets Bull as a miss for the current target; X01 interprets it as a
score. The connector never decides either meaning.
---
# Domain Kits (/docs/packages/domain-kits)
Reuse pure vertical rules, schemas, fixtures, UI, and presentation at build time without creating runtime privilege or member configuration.
A Domain Kit is a versioned developer dependency bundled into immutable package
bytes. Members do not install it. It receives no runtime capability.
Good Domain Kit contents:
* chess move legality, FEN/PGN parsing, and board components;
* dart segment normalization, checkout rules, and board geometry;
* speedrun route/split models and timing presentation;
* FPS benchmark result schemas and common trend calculations;
* pure fixtures, assets, and theme primitives for one coherent domain.
Bad Domain Kit contents:
* a database client;
* network access;
* account/session lookup;
* mutable shared runtime state;
* Station or OBS control;
* a hidden service that installed packages call dynamically.
## Provenance [#provenance]
The package declares exact Domain Kit identity and version. Packing records its
digest and verifies that the kit is bundled into release bytes. Review can prove
which rules influenced a result without trusting a loose `package.json` range.
## Game Pack versus Domain Kit [#game-pack-versus-domain-kit]
A game-specific package or Experience Suite may use a Domain Kit internally,
but the member should discover a complete Pursuit-native experience. A Valorant
member installs the curated Valorant Suite, not a generic FPS kit they must
configure.
## Build one only after real repetition [#build-one-only-after-real-repetition]
Extract a Domain Kit when at least two honest experiences share substantial
pure behavior or when one demanding vertical needs a carefully reviewed reusable
foundation. Avoid speculative abstraction that erases the domain language
members and creators care about.
---
# Package evolution and release compatibility (/docs/packages/evolution)
Ship fixes and improvements while preserving pinned runs, historical evidence, and honest progression lanes.
Never replace bytes for a published semantic version. Build a new version and
classify how it relates to the exact prior archive.
## Compatible presentation change [#compatible-presentation-change]
Examples:
* responsive layout improvement;
* accessibility correction;
* copy or visual polish;
* overlay animation change;
* bug fix that does not affect any declared result fixture.
The result and progression lanes may remain comparable after differential proof.
## New result lane [#new-result-lane]
Examples:
* scoring rule correction;
* changed Attempt terminal condition;
* altered configuration semantics;
* previously accepted observation now interpreted differently;
* new primary metric or unit.
Historical Attempts keep their pinned result contract. New evidence enters the
new lane unless a reviewed migration proves equivalence.
## New progression lane [#new-progression-lane]
Changing rank thresholds or aggregation can preserve raw result comparability
while producing a new progression definition. Both ladders remain attributable
to their exact policy version.
## Active run safety [#active-run-safety]
An active Attempt or Live Run continues with the release and capability versions
it began with. Updating the installation affects future runs only. Rollback
selects another immutable release for future runs; it never mutates evidence.
## Evolution command [#evolution-command]
```bash
npm run cm -- evolution --from ./previous-release.cmpkg
```
The report compares manifests, schemas, declared contracts, artifacts, and
representative fixture behavior. Resolve every breaking finding deliberately;
do not edit the report or bump a version until it turns green.
---
# Packages and Practice Modes (/docs/packages)
Build immutable portable experiences that own domain meaning while the host retains authority.
A package is the deployable unit for one or more Practice Modes and their
presentation. One package may contribute deterministic activities, progression,
Story Events, a rich player, overlays, coordination, narration, and package-owned
configuration defaults.
Members should experience a coherent **Experience Suite**, not an installation
wizard. Adding the Suite provisions every included Practice Mode from the
immutable package defaults so rankings and progress remain aligned across the
Pursuit.
## Package capability map [#package-capability-map]
| Contribution | Question it answers | Executed by |
| ------------ | ------------------------------------------------------- | -------------------------- |
| Activity | What happens when this input arrives? | isolated runtime worker |
| Progression | How does comparable evidence map to ranks? | trusted host projection |
| Story Event | Which committed facts matter to viewers/editors? | host after activity commit |
| `web_ui` | How does the member perform and understand the Attempt? | opaque iframe or WebView |
| Overlay | What should a viewer see now? | read-only browser source |
| Coordination | Who may act, and when is a match/round complete? | isolated policy worker |
| Narration | Which committed facts deserve a bounded cue? | isolated policy worker |
## Learn in this order [#learn-in-this-order]
## Small first, deep eventually [#small-first-deep-eventually]
The best first implementation proves one excellent Practice Mode end to end.
The complete vertical can add more modes, a shared Domain Kit, automatic input,
corrections, coordination, narration, and creator tooling without changing the
core trust boundary.
The [Darts capability trace](/docs/verticals/darts-reference) shows how those layers compose
without turning the package into a trusted monolith.
---
# Input and package-owned UI (/docs/packages/input-and-ui)
Build a simple host form or a rich portable player, and make every evidence path converge on one domain reducer.
## Choose the lightest honest input [#choose-the-lightest-honest-input]
Use a host-rendered declarative form for one bounded submission: a score, time,
percentage, pass/not-yet result, short text, or a small fixed set of fields.
Use a portable `web_ui` player when an Attempt needs:
* several actions over time;
* a board, map, puzzle, route, or spatial control;
* intermediate state or contextual instructions;
* live automatic observations;
* correction controls;
* custom animation or rich visual feedback.
The same immutable player runs inside a browser iframe and native WebView.
## The bridge [#the-bridge]
Create it with createPortablePackageUiBridge. The
bridge validates and bounds every message and tolerates both browser and native
delivery semantics.
```ts
import { createPortablePackageUiBridge } from "@chasingmastery/sdk";
const bridge = createPortablePackageUiBridge();
const unsubscribe = bridge.subscribe((message) => {
if (message.type === "snapshot") render(message.snapshot);
if (message.type === "command_result") reconcile(message);
});
bridge.send({ type: "snapshot_request" });
```
The player sends only declared intents. The host adds actor, route, trusted
time, expected revision, and idempotency before invoking package behavior.
## Lifecycle requirements [#lifecycle-requirements]
A production player must handle:
* loading before the first authoritative snapshot;
* active interaction;
* a command pending while the UI remains understandable;
* repeated taps without duplicate application;
* reconnect and foreground recovery;
* automatic-input healthy, stale, unavailable, and fallback states;
* terminal result and read-only replay;
* reduced motion, keyboard input, 200% text, and safe touch targets;
* iframe and WebView viewport changes.
The host owns Close, retry of host loading, and generic terminal navigation. The
package owns the activity-specific result meaning and “Practice again” intent.
## Manual and automatic equivalence [#manual-and-automatic-equivalence]
```text
manual: tap “Treble 20” → command → normalized throw
auto: AutoDarts payload → exact observation → normalized throw
↓
one Darts reducer
```
Workbench should run both paths against the same scenario and compare final
state, Measurements, Story Events, and presentation. Automatic input is an
enhancement, not an excuse to leave manual mode broken.
## Security constraints [#security-constraints]
Portable UI cannot request arbitrary fetch, storage, file, camera, microphone,
OBS, clipboard, identity, or account operations. A new bridge message is a new
public capability and requires schema limits, host authorization, fixtures, and
conformance—not an untyped escape hatch.
---
# Measurements and progression (/docs/packages/measurements-and-progression)
Design stable result contracts and rank ladders that remain meaningful outside a Sprint.
Every Practice Mode owns independent lifetime history and progression whether
or not a member currently has a Sprint. If Around the Clock is installed, the
member can practice it whenever they want and retain its rank, recent Attempts,
personal bests, and lifetime metrics.
A Sprint references that evidence; it does not create a second practice history.
## Start with the result contract [#start-with-the-result-contract]
Define:
1. the primary comparable Measurement;
2. its scalar type and unit;
3. whether higher or lower is better;
4. the configuration fields that affect comparability;
5. supporting Measurements that explain the result;
6. what incomplete, aborted, invalid, or corrected evidence means.
Examples:
| Mode | Primary | Direction | Supporting |
| ------------------- | ----------------------- | --------- | -------------------------------- |
| Around the Clock | darts thrown | lower | hit %, singles, doubles, trebles |
| Puzzle Rush | solved count | higher | accuracy, duration, max streak |
| Reaction Time | median milliseconds | lower | false starts, variance |
| Memorization recall | correct sequence length | higher | errors, elapsed time |
## Progression is immutable policy [#progression-is-immutable-policy]
A progression definition selects comparable Attempt evidence, chooses an
aggregation such as best, latest, median, or rolling window, and maps the result
to ordered thresholds. Publish it as immutable package policy.
The host maintains a rebuildable **Progression State** per member, Practice Mode
configuration, and definition version for fast product reads. Attempt history
remains authoritative.
## Rank semantics [#rank-semantics]
Keep the platform rank names consistent while letting each mode define honest
thresholds. The package may calculate a composite primary metric from several
raw Measurements, but the resulting comparable value must be deterministic and
documented.
Do not let ordinary members edit rank-affecting defaults in a shared mode. If a
different ruleset should produce separate progression, give it a distinct
configuration identity or Practice Mode.
## Sprint relationship [#sprint-relationship]
A Sprint finish line can reference one Practice Mode result or rank condition.
When a compatible Attempt commits while the Sprint is active, it contributes
automatically. The same Attempt also updates ordinary mode history and
progression.
A baseline is required for an improvement claim. Absolute targets and first
completion goals may use an explicit unknown or not-yet-achieved starting point.
## Boundary fixtures [#boundary-fixtures]
For each rank, include fixtures immediately below, exactly at, and immediately
above the threshold. Add aggregation fixtures that prove ordering, excluded
evidence, corrections, and rebuild behavior.
---
# Narration policy (/docs/packages/narration)
Turn committed broadcast facts into provider-neutral cues while the host owns voices, synthesis, playback, and failure recovery.
Narration runs after commit and consumes bounded **broadcast facts**. It proposes
what might be said, not how a provider synthesizes or plays it.
## Public interface [#public-interface]
Wrap policy with defineNarrationDirector and the
standard narration worker adapter.
## A cue may specify [#a-cue-may-specify]
* bounded text and optional caption;
* semantic speaker or voice role;
* priority;
* expiry;
* whether it may interrupt another cue;
* cancellation keys when later truth supersedes it.
Intentional silence is a valid plan. The director should suppress repetitive,
stale, low-value, or unsafe narration instead of filling every second.
## Host responsibilities [#host-responsibilities]
The host owns listener modes, voice selection, provider credentials, synthesis,
caching, rate limits, queues, cancellation, playback, captions, observability,
and recovery. A provider outage never changes the Attempt or match outcome.
## Policy scenarios [#policy-scenarios]
* routine progress stays quiet;
* personal best receives a short high-value cue;
* a correction cancels an invalidated callout;
* a higher-priority match outcome interrupts a routine cue;
* expired facts produce silence;
* repeated facts are deduplicated;
* locale and listener mode constrain output without leaking provider details.
---
# Story Events and overlays (/docs/packages/story-and-overlays)
Turn committed domain facts into safe, useful presentation for members, viewers, and editors.
## Emit meaning, not editing instructions [#emit-meaning-not-editing-instructions]
A Story Event describes a verified semantic fact:
* `personal_best`
* `rank_gained`
* `target_cleared`
* `checkout_completed`
* `lead_changed`
* `match_won`
* `streak_extended`
The bounded fact payload carries enough domain context for downstream consumers
to explain the moment. It should not contain HTML, a file path, an OBS scene,
provider credentials, or a request to publish content.
Story effects are processed only after the activity transition commits.
## Retractions [#retractions]
If an authorized correction invalidates a committed moment, deterministic replay
produces the corrected event set and the host emits explicit retractions. Editors
and overlays can reconcile without pretending the first event never existed.
## Read-only overlay [#read-only-overlay]
An overlay is a package artifact rendered from a bounded host snapshot. It may
show activity identity, goal, current/final result, progress, pace or meaningful
change, connection state, stakes, and the next milestone.
It cannot:
* send activity commands;
* control OBS;
* query member history;
* fetch arbitrary network resources;
* retain credentials;
* become a second scoring implementation.
## Shared presentation primitives [#shared-presentation-primitives]
The public Presentation Kit provides pure semantic framing, theme tokens,
safe-area layout, formatting, reduced-motion behavior, and accessibility
primitives. The package still decides what the viewer should care about and
maps domain state into that model.
This lets Split Timer and Reaction Foundations share quality without looking or
behaving like the same activity.
## State matrix [#state-matrix]
Preview at least:
| Activity | Connection | Expected presentation |
| -------- | ----------- | -------------------------------------------------- |
| ready | healthy | goal and how to begin |
| active | healthy | current result/progress and next meaningful action |
| active | stale | last committed truth plus explicit stale status |
| active | unavailable | honest unavailable state and manual fallback |
| terminal | any | final committed result and outcome |
| replay | offline | pinned read-only historical evidence |
Test compact broadcast dimensions and full 16:9 layouts in addition to member
phone, tablet, and desktop viewports.
---
# Workbench (/docs/packages/workbench)
Design, exercise, diagnose, and prove the real package experience before immutable release bytes leave the author workspace.
Workbench is a package development host, not a no-code editor and not a mock
preview. It loads the real activity worker, package player, overlay,
configuration, fixtures, progression, Story Events, correction policy,
coordination, and narration contributions.
## Product view first [#product-view-first]
The main canvas shows the Practice Mode at realistic phone, tablet, desktop, and
broadcast dimensions. The collapsible sidebar contains author controls. Deep
protocol traces and raw diagnostics stay available without dominating the
normal iteration loop.
## Core author loop [#core-author-loop]
### Pick a scenario [#pick-a-scenario]
Use named fixtures for ready, active, edge, terminal, stale, unavailable,
corrected, and replay states. A scenario should describe why the state matters,
not merely dump JSON.
### Exercise the real interaction [#exercise-the-real-interaction]
Tap, type, use keyboard controls, or inject declared exact observations through
the live activity runtime. Inspect state, Measurements, progression, Story
Events, and result presentation together.
### Change viewport and accessibility context [#change-viewport-and-accessibility-context]
Check phone/tablet portrait and landscape, desktop, compact overlay, 16:9
broadcast, 200% text, keyboard focus, reduced motion, contrast, and touch size.
### Diagnose only when needed [#diagnose-only-when-needed]
Open transitions, bridge messages, schema validation, capability grants,
observation identity, and fixture details when behavior is surprising.
### Run conformance [#run-conformance]
Conformance verifies the claims made by the manifest, authoring brief, listing,
fixtures, and artifacts. The release cannot outrun its evidence.
## Automatic input loopback [#automatic-input-loopback]
Connector Lab can feed exact observations through a loopback bridge into the
real Workbench activity. This proves that independently built connector bytes
and package bytes agree on the complete observation identity—not just a sample
JSON shape.
## Workbench does not approve [#workbench-does-not-approve]
Local approval is evidence for a later independent review. Workbench never
publishes public code, grants native capabilities, signs a connector, or marks
its own package trusted.
---
# Activity runtime (/docs/reference/activity)
Exact context, inputs, transition effects, status, presentation, and terminal semantics for one atomic Attempt.
## Run context [#run-context]
The host supplies identity, participants, exact package/release, Practice Mode,
and validated configuration. It does not supply domain state.
## Inputs [#inputs]
`command` is a host-authorized member intent. `observation` is a routed semantic
fact from Station. `correction` asks the pinned package to reinterpret existing
evidence. `coordination` delivers one declared match signal to one participant
Attempt.
## Transition [#transition]
A transition replaces package state and presentation and returns bounded
effects. The host persists the accepted transition atomically, assigns durable
identity, and executes allowed effects after validation.
## Effects [#effects]
`attempt.complete` and `attempt.abandon` are terminal. Completion does not wait
for a later session, overlay, recording, or Stop action. Story, broadcast, and
coordination effects are derived outputs; a downstream failure cannot undo the
committed Attempt.
---
# Agent API and MCP (/docs/reference/agent-api)
Let an authorized coding agent find Pursuits, install Suites, create Sprints, and submit a private package without gaining practice or billing authority.
The `chasing-mastery` MCP server is a stateless typed projection of the same
versioned Member API used by first-party setup flows. It is not a second domain
backend.
## Authorization [#authorization]
Agents use OAuth 2.1 authorization code with PKCE, signed first-party consent,
short-lived audience-bound access tokens, and rotating refresh tokens. Never
paste a browser session, password, store credential, publisher key, Station
credential, or bearer token into a prompt.
| Scope | Allows |
| ----------------- | ----------------------------------------------------------------- |
| `club.read` | search Pursuits and Library listings; inspect bounded setup state |
| `club.manage` | join/create a Pursuit, add a Suite, configure modes and Sprints |
| `packages.submit` | send an exact portable package for owner-private review |
## Allowlisted workflow [#allowlisted-workflow]
An authorized agent can:
1. search and join a listed Pursuit or create a private one;
2. search the Library and inspect an exact listing;
3. idempotently add its Suite and provision package-default modes;
4. create/configure/activate a Sprint;
5. submit a locally authored `.cmpkg` and poll owner-private review status.
It cannot perform Attempts, make purchases, publish a public Pursuit, moderate
community content, approve native connector grants, control Station/OBS, or
bypass package review.
## Protocol endpoints [#protocol-endpoints]
| Endpoint | Purpose |
| -------------------------------------------------- | -------------------------------------- |
| `/.well-known/oauth-authorization-server/api/auth` | authorization-server metadata |
| `/.well-known/oauth-protected-resource/mcp` | resource metadata and supported scopes |
| `/api/auth/oauth2/authorize` | first-party consent |
| `/mcp` | stateless Streamable HTTP MCP |
---
# Connector protocol (/docs/reference/connector)
Exact zero-grant sidecar identity, resources, source inventory, observations, host commands, and lifecycle frames.
## Release and grants [#release-and-grants]
## Sources and observations [#sources-and-observations]
## Sidecar messages [#sidecar-messages]
## Framing [#framing]
All protocol frames are bounded line-delimited JSON. `CONNECTOR_PROTOCOL_VERSION`
is currently `1`; `CONNECTOR_MAX_MESSAGE_BYTES` is the hard serialized frame
limit. The Rust SDK is canonical for native sidecars and provides validated
parsing, serialization, health, and lifecycle helpers.
---
# Creator evidence (/docs/reference/creator-evidence)
Exact Story Event, capture, anchor, export, and immutable Content Studio intake contracts.
## Semantic facts [#semantic-facts]
## Capture alignment [#capture-alignment]
Clock quality and uncertainty are explicit. An anchor is evidence about where a
fact appears in media, not a promise of frame-perfect synchronization when
clock sampling or capture continuity is weak.
## Sealed export [#sealed-export]
## Studio intake [#studio-intake]
The handoff is immutable and idempotent. It carries exact release and evidence
provenance, not Station credentials, OBS passwords, provider keys, or mutable
live-run handles.
---
# Public reference (/docs/reference)
Source-derived TypeScript contracts and bounded host protocols for package authors, connector authors, and agents.
Use the guides to understand *why* the model works. Use this reference when you
need the exact current shape.
## Contract map [#contract-map]
| You are defining | Start here |
| ----------------------------------------- | --------------------------------------- |
| Package manifest and contributions | [Package manifest](./package-manifest) |
| Deterministic reducer input/output | [Activity runtime](./activity) |
| Browser/WebView player messages | [Portable UI bridge](./ui-bridge) |
| Player and overlay projection | [Activity Presentation](./presentation) |
| Station sidecar frames | [Connector protocol](./connector) |
| OBS/media production handoff | [Creator evidence](./creator-evidence) |
| Club setup through an agent | [Agent API and MCP](./agent-api) |
| Payload, collection, and lifecycle bounds | [Limits and versions](./limits) |
The rendered type tables on this site are generated from the checked TypeScript
source during the docs build. The docs integrity gate also verifies referenced
symbols and source paths, so a rename cannot silently leave a plausible-looking
stale reference.
## Stability model [#stability-model]
* A package pins required capability versions and a host compatibility range.
* Schemas use explicit names and schema versions.
* An active run stays pinned to exact release and configuration identity.
* An immutable release is never edited in place.
* Compatibility is a reviewed claim, not an inference from semantic version
alone.
For machine-readable navigation, use [`/docs-manifest.json`](/docs-manifest.json),
[`/llms.txt`](/llms.txt), or [`/llms-full.txt`](/llms-full.txt). Every guide also
has a **Copy Markdown** action.
---
# Limits and versions (/docs/reference/limits)
Design within explicit protocol, payload, collection, artifact, and lifecycle bounds instead of discovering them in production.
Limits protect deterministic execution, mobile hosts, Station recovery, and
reviewability. Exact schema maxima remain authoritative; this page highlights
the boundaries authors most often need.
| Boundary | Current contract |
| ------------------------------------- | ------------------------------------------------------------- |
| Package UI message | `PACKAGE_UI_MAX_MESSAGE_BYTES` |
| Connector protocol frame | `CONNECTOR_MAX_MESSAGE_BYTES` (64 KiB) |
| Station observation | `STATION_OBSERVATION_MAX_BYTES` (64 KiB) |
| Station delivery batch | `STATION_BATCH_MAX_OBSERVATIONS` (50) |
| Activity effects per transition | 128 |
| Metrics per activity | 64 contract maximum; author brief intentionally narrows to 16 |
| Artifacts / contributions per package | 128 each |
| Creator event delivery page | 100 items |
| Creator capture clock samples | 512 |
| Creator media anchors | 5,000 |
| Creator upload part | 8 MiB |
Do not split one semantic fact merely to evade limits. If a real vertical
cannot fit, document representative evidence and propose a contract tranche.
## Version identities are separate [#version-identities-are-separate]
Keep these concepts distinct:
* package semantic version: immutable released bytes;
* capability version: host/extension feature contract;
* configuration version: interpretation of saved mode setup;
* result-contract revision: whether Measurements remain comparable;
* progression definition version: rank thresholds and evidence policy;
* observation contract version + payload digest: exact source semantics;
* schema version: serialization shape for one named protocol.
An update can advance one without advancing all. The [evolution guide](../packages/evolution)
explains when history must split.
---
# Package manifest (/docs/reference/package-manifest)
Declare identity, compatibility, artifacts, capabilities, permissions, provenance, migrations, and portable contributions.
The manifest is executable intent, not marketing copy. Workbench and review
resolve every reference and reject missing artifacts, contradictory capability
claims, unsafe paths, invalid contribution links, or undeclared authority.
## Contribution types [#contribution-types]
| Kind | Owns |
| -------------- | --------------------------------------------------------------------------- |
| `activity` | one Practice Mode engine, contracts, default, inputs, and correction policy |
| `progression` | versioned rank projection over one activity |
| `story_events` | declared semantic story vocabulary |
| `overlay` | read-only OBS/viewer/scoreboard presentation |
| `coordination` | multiplayer policy around participant Attempts |
| `narration` | provider-neutral fact-to-cue policy |
| `connector` | reviewed Station sidecar artifact and observation declaration |
Connectors are normally released and reviewed separately from portable activity
packages even though the common manifest can describe their artifacts.
## Artifacts [#artifacts]
Every artifact has content identity, byte count, media type, target, and role.
Packing replaces author-workspace placeholders with exact archive metadata.
## Permissions [#permissions]
Portable activity packages usually need no ambient permission. A declared
permission is a narrow review request, not an automatically granted capability.
## Result identity [#result-identity]
Bump the result revision whenever old and new Measurements must not share a
progression lane. UI layout and artifact bytes are deliberately not result
identity.
---
# Activity Presentation (/docs/reference/presentation)
A bounded semantic projection for rich players and useful overlays without moving domain meaning into the host.
Activity Presentation describes the member's goal, current status, stakes,
meaningful change, next milestone, connection/evidence quality, and terminal
outcome. Packages decide what those fields mean; generic hosts decide only how
to isolate and deliver them.
## Why it is separate from state [#why-it-is-separate-from-state]
Engine state is sufficient for deterministic continuation and replay. A
presentation projection is the bounded, intentionally shareable subset that a
player or viewer needs. Do not send an entire reducer state to an OBS overlay.
## Surface states [#surface-states]
Every player and overlay should explicitly handle ready, live, terminal,
disconnected/stale, replay, reduced-motion, compact, and broadcast-safe states.
Connection quality is evidence quality—not a license to fabricate progress.
---
# TypeScript SDK (/docs/reference/sdk)
The small public helper layer that validates packages, engines, worker adapters, and portable UI messages.
The package SDK re-exports public contracts and adds validated author helpers.
It deliberately does not expose persistence, member data, Station, OBS,
filesystem, network, or provider authority.
## Engine contracts [#engine-contracts]
## Portable bridge [#portable-bridge]
## Validated helpers [#validated-helpers]
| Helper | Purpose |
| ---------------------------------------------- | ------------------------------------------------------------------------- |
| `definePackage` | Parse the full manifest and every contribution. |
| `defineActivityEngine` | Validate descriptions, contexts, inputs, and transitions on direct calls. |
| `defineCoordinationEngine` | Validate rosters, signals, and match transitions. |
| `defineNarrationDirector` | Validate provider-neutral narration plans. |
| `createActivityWorkerHandler` | Expose one engine through the isolated runtime protocol. |
| `createCoordinationWorkerHandler` | Expose deterministic coordination policy. |
| `createNarrationWorkerHandler` | Expose fact-to-cue planning. |
| `createPortablePackageUiBridge` | Use one bounded transport in iframe and WebView hosts. |
| `parsePackageUiMessage` / `parseHostUiMessage` | Validate portable UI frames at boundaries. |
Prefer these wrappers to custom transport or ad hoc validation. They keep local
tests, Workbench, and production execution on the same contract.
---
# Portable UI bridge (/docs/reference/ui-bridge)
The bounded, capability-aware protocol shared by browser iframes, native WebViews, Workbench, and read-only replay.
The host owns the transport. Package UI owns rendering and domain interaction.
Both validate every frame.
## Package to host [#package-to-host]
A package may report readiness, request one declared command, or request one
supported correction. The message contains intent—not member authorization,
trusted time, expected revision, or persistence identity. The host adds and
validates those fields.
## Host to package [#host-to-package]
The host supplies a bounded context or state snapshot, lifecycle state,
declared capabilities, acknowledgements, and safe errors. A replay/overlay host
can omit command and correction capability while rendering the same artifact.
## Capability checks [#capability-checks]
Disable or hide actions the host did not grant. Never infer capability because
the page happens to be running in Workbench, a browser, or a WebView.
## Size and trust [#size-and-trust]
`PACKAGE_UI_MAX_MESSAGE_BYTES` bounds serialized frames. Unknown, malformed, or
oversized messages are ignored or rejected. Package UI never receives browser
credentials, direct API access, account storage, or a wildcard network grant.
---
# Compatibility and evolution (/docs/release/compatibility)
Decide whether a change can share history, needs migration, requires a new result lane, or must remain pinned to old runs.
Package versions are immutable. An update produces a new release, and review
classifies the semantic change.
| Change | Typical treatment |
| ------------------------------------------------------ | ---------------------------------------------------- |
| Layout, copy, accessibility, animation | presentation-compatible update |
| Bug fix preserving all semantic fixtures | compatible only with differential proof |
| New optional mode | additive Suite release; old mode lanes remain |
| Saved configuration shape | explicit forward migration |
| Default exercise meaning | new configuration identity and review |
| Metric key, unit, direction, precision, or calculation | new result-contract revision |
| Progression thresholds/window/evidence | new progression version and retained lane |
| Observation payload meaning/schema | new exact protocol identity and binding verification |
## Active and historical behavior [#active-and-historical-behavior]
* An active run keeps the release and capability versions it began with.
* Upgrade affects future runs only after review and install-plan application.
* Old Attempts remain readable with their exact provenance.
* Rollback selects an older approved release for future runs; it never rewrites
evidence already committed by a newer release.
* A compatible presentation update must not require a result-history rewrite.
Run the project-local `evolution` command against the retained prior archive.
Treat its report as review input, not permission to override an incompatible
change.
---
# Release and review (/docs/release)
Prepare immutable package or connector bytes, prove them locally, and preserve enough evidence for independent review.
Release is a transition from editable author workspace to immutable artifact.
Do not upload a source directory and ask production to build it.
### Freeze the authoring brief [#freeze-the-authoring-brief]
Confirm Attempt boundaries, Measurements, progression, input, corrections,
presentation, story, and acceptance scenarios still match the implementation.
### Run readiness locally [#run-readiness-locally]
The project-local toolchain validates schemas, fixtures, deterministic engines,
portable UI, overlay, responsive states, capability links, provenance, and
archive safety.
### Compare evolution [#compare-evolution]
If a previous release exists, classify result, metric, preset, progression,
observation, configuration, and presentation changes before choosing a version.
### Pack exact bytes [#pack-exact-bytes]
Produce a self-contained `.cmpkg` with canonical manifest, content digests,
artifact sizes, bundled Domain Kits, and no secret or unsafe path.
### Submit privately [#submit-privately]
Upload through the member product or scoped MCP. Independent review replays the
artifact and returns bounded diagnostics. Submission is not publication.
An approved immutable release can then back a private install or reviewed
Library listing. Public discovery and native connector authority require
separate product review decisions.
---
# Preflight checklist (/docs/release/preflight)
The minimum evidence package and connector authors should close before creating release bytes.
## Portable package [#portable-package]
* Authoring brief matches current behavior.
* Manifest, contribution links, schemas, and artifacts validate.
* Every mode has one useful immutable default.
* Scenario fixtures cover success, abandonment, invalid input, duplicate input,
terminal input, and relevant edge cases.
* Reducers are deterministic and JSON bounded.
* Manual controls are keyboard, touch, screen-reader, and reduced-motion ready.
* Player and overlay pass phone, tablet, desktop, portrait, landscape, compact,
and broadcast states that are relevant.
* Progression uses the declared primary comparable metric.
* Story Events are semantic and bounded.
* Corrections and retractions behave consistently.
* Secrets, undeclared network calls, unsafe paths, symlinks, and mutable runtime
dependencies are absent.
## Station connector [#station-connector]
* Handshake identity and observation contracts match reviewed artifacts.
* Source discovery is bounded and stable.
* Configuration and grants are narrow and declared.
* Connector Lab passes normal, duplicate, reconnect, degraded, revoked, stop,
shutdown, malformed-message, and oversized-frame fixtures.
* Stdout contains protocol frames only; diagnostics are safe and secret-free.
* Live input verification does not create an Attempt.
* Delivery receipts and recovery preserve at-least-once safety without semantic
duplication.
## Evidence to retain [#evidence-to-retain]
Keep typed reports, fixture inputs and expected results, artifact digest and
size, safe logs, accessibility results, screenshots, and evolution findings.
Do not retain live access tokens or raw personal source data.
---
# Private review and install (/docs/release/private-review)
Return a local artifact safely to one member before any public Library or connector distribution decision.
The first release path is intentionally owner-private.
1. Build and pack the exact artifact locally.
2. Authorize the Chasing Mastery plugin with `packages.submit` when using an
agent, or use the equivalent first-party upload.
3. Submit the `.cmpkg` with bounded Pursuit/Sprint return context.
4. Poll the same submission; do not create duplicates while review is running.
5. Read bounded diagnostics, fix the workspace, bump/repack when bytes change,
and submit the new immutable candidate.
6. After approval, install the exact release and exercise it through the real
member host—not a privileged development route.
Private approval does not create a public Library listing, certify a publisher,
grant native connector resources, or promise future compatibility.
Run the package-local readiness workflow, inspect every failure, compare against
the prior immutable release if one exists, pack exact bytes, and summarize the
artifact digest and retained evidence. Ask for OAuth authorization only when
ready to submit. Submit once with owner-private visibility, poll that exact
submission, and never expose tokens or credentials in output.
---
# Vertical acceptance matrix (/docs/verticals/acceptance-matrix)
Prove rules, package behavior, input equivalence, product journeys, creator evidence, and release integrity at the right layers.
One giant UI test is not sufficient evidence. A deep vertical closes through a
layered matrix whose failures explain what broke.
| Layer | Required proof |
| ------------------ | ------------------------------------------------------------------------------- |
| Pure domain | rules, normalization, edge cases, exact metrics, deterministic fixtures |
| Engine conformance | initialization, revisions, idempotency, terminal behavior, effects |
| Input equivalence | paired manual/automatic sequences produce identical semantic outcomes |
| Workbench | real player, overlay, lifecycle, viewports, reduced motion, accessibility |
| Connector Lab | raw source fixture, protocol lifecycle, exact observation, diagnostics |
| Runtime/API | release pinning, persistence, history, progression, Sprint evidence, isolation |
| Member product | Library → installed Suite → Attempt → result → repeat, on real hosts |
| Creator | Story Events → Station → OBS clock → anchors → sealed evidence → Studio |
| Evolution | presentation-compatible upgrade, breaking lane split, rollback, old-run pinning |
## Failure cases are part of the product [#failure-cases-are-part-of-the-product]
Inject at least:
* duplicate commands and observations;
* stale source revision and reconnect replay;
* connector unavailable before and during an Attempt;
* manual fallback while automatic input is unavailable;
* invalid schema identity and revoked grant;
* overlay, narration, capture, and Studio unavailable after commit;
* active and terminal correction with Story Event retraction;
* package upgrade while an older run remains active.
The invariant is simple: authoritative activity commit never waits for a
derived consumer. A disconnected overlay or failed narration may reduce the
creator experience, but it cannot erase valid practice.
## Retained evidence [#retained-evidence]
A release gate should produce a typed report with exact source fingerprint,
stage results, artifact digests, fixtures, safe logs, JUnit where useful,
screenshots, accessibility results, and clear deferrals. Cached evidence is
reusable only when every relevant source byte and retained prefix artifact is
unchanged.
## Darts commands to study [#darts-commands-to-study]
Physical hardware and subjective art direction remain deliberate launch checks;
they do not replace deterministic correctness and they should not block earlier
engineering tranches.
---
# Vertical blueprint (/docs/verticals/blueprint)
Design the pursuit, suite, evidence, progression, presentation, creator story, and proof before writing package code.
The blueprint is the product contract for a deep vertical. It prevents a valid
SDK implementation from becoming a shallow collection of unrelated modes.
## 1. Map the real ecosystem [#1-map-the-real-ecosystem]
Document the community's accepted practice methods, specialist tools, common
metrics, creator workflows, overlays, terminology, failure modes, and gaps.
For each existing tool, choose deliberately:
| Choice | Use it when |
| ---------- | ----------------------------------------------------------------------------------------- |
| Integrate | The tool is trusted and emits useful evidence through a safe boundary. |
| Complement | It executes practice well, but goals, progression, story, or creator context are missing. |
| Build | No good tool exists, or an owned mode creates a materially better experience. |
| Defer | Evidence would require brittle, invasive, anti-cheat-sensitive, or unsafe access. |
## 2. Define the Pursuit-native promise [#2-define-the-pursuit-native-promise]
Name the people served, the progress they care about, and the reason the suite
belongs together. The Pursuit is the shared community; the Experience Suite is
the coherent toolset recommended inside it.
The ordinary member should not assemble implementation primitives. Joining a
Pursuit can provision its reviewed default Suite, and every included mode should
have one immutable package-owned preset that works immediately.
## 3. Shape the Practice Modes [#3-shape-the-practice-modes]
For every mode, specify:
* the real-world exercise and terminal boundary;
* one primary result contract and any supporting Measurements;
* comparison direction, units, precision, and evidence policy;
* valid goal shapes: improve a metric, reach a target, or complete once;
* manual interaction and accessibility;
* accepted semantic observation protocols;
* correction policy and replay consequences;
* meaningful Story Events and presentation states.
Avoid one enormous configurable mode when practitioners understand the
exercises as independent skills. Separate modes preserve honest history and
make rankings intelligible.
## 4. Design source-neutral rules [#4-design-source-neutral-rules]
```text
portable player command ────┐
├── normalize → domain action → pure reducer
reviewed observation ───────┘
```
Manual and automatic input should differ only before normalization. Equivalent
fixtures must finish with the same package state, status, Measurements, Story
Events, and presentation.
## 5. Design progression without inventing truth [#5-design-progression-without-inventing-truth]
Progression is a rebuildable projection over comparable Attempts. Fix the
metric, aggregation window, evidence minimum, levels, ordering, and definition
version. Never silently mix a changed metric, default, observation meaning, or
threshold policy into an old lane.
## 6. Design the audience experience [#6-design-the-audience-experience]
The player helps the member act. The overlay helps someone else understand.
Define goal, current state, stakes, meaningful change, next milestone, stale or
disconnected evidence, and terminal outcome. Emit a small semantic story
vocabulary rather than raw telemetry.
For Creator use, explain how Story Events align with a capture clock, how gaps
are represented, and what an editor receives in the sealed evidence handoff.
## 7. Decide what belongs where [#7-decide-what-belongs-where]
| Concern | Correct artifact |
| -------------------------------------------------------------------- | -------------------- |
| Pure rules, schemas, fixtures, reusable UI primitives | Domain Kit |
| Modes, engines, player, overlay, progression, story policy | Portable package |
| Native/local source discovery and translation | Station connector |
| Identity, authorization, persistence, clocks, routing, OBS, recovery | Chasing Mastery host |
## 8. Write the acceptance story first [#8-write-the-acceptance-story-first]
Keep one representative end-to-end journey concrete: discover the Pursuit,
receive its Suite, choose a mode, record a manual Attempt, record an equivalent
automatic Attempt, see progression, use a Sprint, inspect the overlay, anchor a
Story Event to media, and seal creator evidence. Add failure injection for
duplicates, reconnect, unavailable consumers, revocation, and corrections.
Create a vertical blueprint using these eight sections. Cite the current public
contract or a proposed missing capability for every behavior. Mark unknowns and
unsafe evidence sources explicitly. Do not write host special cases and do not
claim automatic input until an exact observation path can be tested.
---
# Darts, end to end (/docs/verticals/darts-reference)
Trace the demanding Darts reference implementation through every public SDK, Station, creator, and release boundary.
Darts Core is the proof that the extension platform can support a rich vertical
without privileged Darts behavior in the host. It contains eight modes, three
rule families, manual and automatic input, four progression lanes, corrections,
overlays, matches, narration, OBS synchronization, and immutable Studio intake.
## What the member receives [#what-the-member-receives]
Adding the official Darts Experience Suite provisions all eight immutable
package defaults. There is no rank-threshold form and no required setup step.
| Practice Mode | Primary experience | Important Measurements | Progression |
| ------------------------ | -------------------------- | ------------------------------------------ | ------------------- |
| Around the Clock | Clear singles 1–20 | darts used, target accuracy | Singles Accuracy |
| Around the Clock + Bull | Clear 1–20 and bull | darts used, target accuracy | independent history |
| Doubles Around the Clock | Clear every double | darts used, target accuracy | independent history |
| Trebles Around the Clock | Clear every treble | darts used, target accuracy | independent history |
| 100 Darts at 20 | Score 100 darts at 20 | target score, three-dart average, accuracy | Scoring at 20 |
| Doubles Rotation | Practice finishing doubles | darts used, target accuracy | Doubles Finishing |
| 501 | Double-out X01 | three-dart average, darts used, busts | X01 Matchplay |
| 301 | Faster double-out X01 | three-dart average, darts used, busts | independent history |
Each completed Attempt is terminal by itself. A member can practice any mode
with no Sprint, or let a compatible Attempt advance an active Sprint.
## The artifact graph [#the-artifact-graph]
```text
@chasingmastery/darts-domain-kit
pure rules · target normalization · board geometry · checkout policy · fixtures
│ bundled with provenance
▼
club.chasingmastery/darts-core@0.4.0
8 engines · player · overlay · progressions · story · matches · narration
▲ exact observation contract
│
club.chasingmastery/autodarts
separately reviewed Station sidecar · source health · visit snapshots
```
The Domain Kit is a build-time dependency, not a mutable production service.
The `.cmpkg` release is self-contained. The AutoDarts connector is separately
installed, reviewed, granted, bound, verified, and revocable.
## One source-neutral reducer [#one-source-neutral-reducer]
The portable dartboard sends `darts.throw` with canonical segments such as
`S20`, `D16`, `T19`, `SB`, `DB`, or `MISS`. AutoDarts sends an exact cumulative
visit snapshot. The package converts both into the same ordered throw facts
before applying an ordered-target, fixed-count, or X01 rule family.
```text
darts.throw command ───────────┐
├─ canonical throw → rule family → transition
AutoDarts visit observation ───┘
```
That distinction catches subtle failures. A bull hit while aiming at 20 is a
valid off-target miss—not an invalid numbered segment. Duplicate cumulative
visits, stale source revisions, reconnect replay, and partial visits are
deduplicated before they can corrupt the Attempt.
## Attempt and correction semantics [#attempt-and-correction-semantics]
Every accepted throw receives a stable package transition key. Ordinary input
creates immutable evidence. A later host-authorized replace or remove
correction replays the exact pinned package release from that evidence, creates
a new Attempt revision, retracts obsolete Story Events, and rebuilds
progression and Sprint projections. A terminal Attempt reopens only when the
corrected rules require it.
This is intentionally stricter than a pre-terminal UI undo. The package declares
correction meaning; the host authorizes and persists the revision.
## Player and overlay [#player-and-overlay]
The same package-owned player artifact runs in a browser iframe, native
WebView, and Workbench. It owns board geometry, target state, visit input,
checkout guidance, correction intent, terminal result, keyboard/touch
interaction, and responsive presentation.
The read-only overlay consumes bounded Activity Presentation. It explains the
current target or score, pace, goal, change, next milestone, connection quality,
and terminal outcome without receiving command or correction capability.
## Progression and history [#progression-and-history]
The package fixes four progression definitions: Singles Accuracy, Scoring at
20, Doubles Finishing, and X01 Matchplay. The host projects each member's state
from comparable Attempts and retains the exact definition/configuration lane.
Changing result meaning or evidence policy creates a new revision or lane;
presentation improvements can remain comparable.
## Coordination [#coordination]
The package contributes match policy for 501, 301, and 100 Darts at 20. The
host owns Live Run identity, invitations, participants, readiness, presence,
recovery, and routing. Package policy owns scoring, eligible turns, legs,
winners, outcomes, rematches, and domain presentation.
* `shared_sequenced` routes one physical board only to the eligible player.
* `independent` lets remote participants use separate authorized inputs.
* A match remains coordination around atomic Attempts, never a replacement for
ordinary practice history.
## Narration and creator evidence [#narration-and-creator-evidence]
X01 engines emit declared broadcast facts. A package-owned narration director
maps them to provider-neutral captions, voice roles, priority, expiry, pacing,
and cancellation. The host owns audio provider credentials and playback.
Narration failure never blocks a throw.
Committed Story Events travel independently to Station. Station samples the OBS
capture clock and creates media anchors; corrections produce retractions. The
sealed creator evidence pins package releases, Attempt revisions, Measurements,
Story Events, gaps, media digests, and capture timing before Content Studio
receives an immutable intake.
## Source map: learn from the implementation [#source-map-learn-from-the-implementation]
## Reproduce this depth in another Pursuit [#reproduce-this-depth-in-another-pursuit]
Do not copy Darts identifiers. Reproduce the pattern:
1. Extract pure domain truth and paired manual/automatic fixtures.
2. Publish a coherent multi-mode Suite with useful immutable defaults.
3. Normalize every input source into the same domain actions.
4. Keep result contracts and progression lanes explicit and versioned.
5. Build a rich member player and a separate read-only viewer overlay.
6. Emit semantic story facts; add coordination and narration only where real.
7. Prove the complete journey through public artifacts and retained evidence.
Study this page and the linked source files. Produce a vertical blueprint and a
capability matrix before code. Use only public SDKs. For every Darts capability,
either map an equivalent domain requirement, explain why it is not relevant, or
defer it with a concrete reason. Preserve atomic Attempts, source-neutral rules,
immutable releases, exact observation identity, and host-owned authority.
---
# Build a complete vertical (/docs/verticals)
Go beyond a metric form or connector and make one pursuit community feel deeply understood.
A package can be technically valid and still be a weak product. A complete
vertical combines the public extension points into a pursuit-native experience
that serious practitioners would actually choose.
## The standard is depth [#the-standard-is-depth]
A launch-quality vertical should answer all of these questions:
* What do skilled practitioners actually practice, and why?
* Which existing tools should Chasing Mastery integrate rather than replace?
* Which Practice Modes are missing or materially better when owned here?
* What can be observed with almost no effort from the member?
* Which Measurements remain comparable over time?
* What makes progress legible during a stream and useful in an edit?
* Which failure states preserve trustworthy practice history?
The member should discover a deliberate **Darts**, **Chess**, or **Trackmania**
experience—not install a generic category package and configure the product's
meaning themselves.
## Use public composition, not privileged code [#use-public-composition-not-privileged-code]
Every official vertical is built through the same contracts available to an
external author. Domain logic belongs in a Domain Kit or immutable package.
Native observations come through a separately reviewed Station connector. The
host remains domain-neutral.
## Recommended route [#recommended-route]
1. Write the [vertical blueprint](./blueprint) before implementation.
2. Build one honest manual-input gold path in Workbench.
3. Add the lowest-friction evidence path without changing the reducer.
4. Add progression, story, presentation, and creator evidence in that order.
5. Use the [Darts reference](./darts-reference) to see each seam exercised.
6. Close the [acceptance matrix](./acceptance-matrix) with retained evidence.
Read `/llms-full.txt`, then follow the complete-vertical path. Do not add domain
branches to the Chasing Mastery host. Begin with a vertical brief covering the
real practice ecosystem, Experience Suite, Practice Modes, Measurements,
input sources, story vocabulary, creator journey, and acceptance fixtures.