# SOP — WaterStorage Watershed Cross-Platform Build

**Project:** WaterStorage — Watershed
**Interfaces:** CookieBlob browser rooms + Game Crafter physical game
**Version:** 0.1
**Started:** 2026-07-17
**Status:** Active project seed

## 1. Purpose

This SOP governs the parallel construction of the Watershed experience as:

1. a persistent browser-based CookieBlob system hosted through WordPress Custom HTML rooms; and
2. a physical tabletop game prepared for Game Crafter production.

The two interfaces must share one rules substrate. The browser is not a demo of the physical game, and the physical game is not a printout of the browser. Each interface should make the same WaterStorage transitions tangible in its own medium.

## 2. Canonical source order

When sources disagree, use this order:

1. the user's latest product decision;
2. this SOP;
3. `shared/` machine-readable model and transition table;
4. `WaterStorage/framework.md`;
5. existing CookieBlob engine conventions and prior prototypes;
6. interface-specific implementation notes.

Historical proposals remain useful context but do not override a newer product decision.

## 3. Shared design contract

The first release uses the WaterStorage phase cycle:

1. Ocean — raw signal
2. Evaporation — uplink and energy expenditure
3. Clouds — distributed field-state
4. Precipitation — trigger-based landing
5. Soil Surface — first contact and triage
6. Streamlines — medium-shaped routing
7. Creeks/Rivers — structured retrieval
8. Lakes/Reservoirs — domain storage
9. Groundwater — deep memory
10. Return to Ocean — feedback closure

The framework's hydrodynamic language remains an analogy and design substrate, not a claim that information systems literally are colloidal fluids.

Both interfaces must express these shared invariants:

- evaporation requires energy;
- precipitation requires a trigger and suitable receiving conditions;
- terrain changes where precipitation lands;
- streamlines are distinct from indexed storage;
- reservoirs are useful but can stagnate or overload;
- groundwater preserves slow memory and can be polluted;
- no state is permanently deleted; it changes phase or becomes inaccessible;
- a healthy session closes the loop through Return to Ocean.

## 4. Shared state model

The common model should remain small enough to implement in JavaScript and on paper:

```json
{
  "schema": "waterstorage-watershed-v0.1",
  "phase": "ocean",
  "energy": 4,
  "flow": 5,
  "pressure": 0,
  "groundwater_health": 5,
  "pollution": 0,
  "channels": [],
  "reservoirs": [],
  "memories": [],
  "triggers": [],
  "cycle_count": 0,
  "notes": []
}
```

The browser may add UI metadata such as visited rooms, timestamps, export history, and browser identifiers. The tabletop game may use tokens and tracks. Those additions must not change the meaning of the shared fields.

## 5. Interface rules

### 5.1 CookieBlob / Watershed

- Use a dedicated storage key: `waterstorage_watershed_v1`.
- Do not modify or depend on the existing `tenchi_blob` or `cookieblob_state` saves.
- Every room must work when opened directly.
- Every room must show current state and explain why a choice is unavailable.
- Choices must use buttons and explicit state handlers rather than fragile inline JavaScript.
- State-changing choices must save before navigation.
- Export/import must use JSON and include a schema version.
- Room descriptions may be poetic, but requirements and consequences must be mechanically clear.
- A browser visitor may revisit rooms; revisiting should reveal changed terrain rather than reset progress.

Initial browser slice:

1. Ocean room: receive one raw signal.
2. Clouds room: spend energy to abstract it into field-state.
3. Precipitation room: choose whether conditions are ready for landing.

### 5.2 Game Crafter / Watershed

- The base game must be playable without a website, app, or framework document.
- Prototype with paper cards, ordinary counters, and a hand-drawn mat before commissioning art.
- Keep the base game to four numeric tracks: energy, flow, pressure, groundwater health.
- Use tokens for pollution, channels, reservoirs, and memories rather than adding more tracks.
- Use cards for triggers and phase events so the physical game has changing weather.
- The first physical slice must use the same three transitions as the browser slice.
- Every card must state its trigger, cost, effect, and next available phase.

## 6. Seed interchange

The two interfaces exchange portable seeds, not live sessions. A seed must contain only shared model fields plus a short human-readable note:

```json
{
  "schema": "waterstorage-seed-v1",
  "source": "cookieblob",
  "phase": "clouds",
  "energy": 3,
  "flow": 6,
  "pressure": 2,
  "groundwater_health": 5,
  "pollution": 0,
  "channels": ["first-streamline"],
  "reservoirs": [],
  "memories": ["a signal became ambient"],
  "triggers": ["temperature-drop"],
  "cycle_count": 1,
  "note": "The field is carrying more than the visitor can see."
}
```

A seed exported from CookieBlob can become a Game Crafter setup card. A physical session can be recorded as a seed and imported back into the browser experience.

## 7. Build stages

### Stage 0 — Seed and contract

- Create this SOP and public package.
- Create the shared model, seed schema, transition table, and scenario list.
- Record all unresolved design questions in one file; do not scatter competing plans.

### Stage 1 — Three-phase vertical slice

- Implement Ocean, Clouds, and Precipitation in CookieBlob.
- Prototype matching phase cards and a small mat section for Game Crafter.
- Test four scenarios: healthy evaporation, insufficient energy, early precipitation, and successful landing.

### Stage 2 — Shared playtest

- Run each scenario in both interfaces.
- Compare resulting state fields, not prose or visual presentation.
- Log any divergence with the exact input state, action, expected result, and observed result.

### Stage 3 — Full cycle

- Add Soil Surface through Return to Ocean.
- Add pollution, groundwater rehabilitation, reservoir overload, and loop-closure rules.
- Keep the shared state model stable unless a playtest demonstrates a real deficiency.

### Stage 4 — Production preparation

- CookieBlob: produce WordPress-safe room blocks, navigation links, save manager, and import/export testing notes.
- Game Crafter: produce card list, mat specification, token list, print dimensions, and a prototype rulesheet.
- Generate art only after mechanics and component counts are stable.

### Stage 5 — Release candidates

- Freeze a shared model version.
- Run a clean browser test from empty storage.
- Run a complete paper prototype session.
- Export a seed from each interface and verify cross-import manually.
- Publish the final package and report the exact collection URL.

## 8. QA checklist

Before accepting a change:

- Does the same action produce the same shared state in both interfaces?
- Is the transition cost visible to the player?
- Can a player tell why a transition is blocked?
- Does the system preserve state across revisit or turn boundaries?
- Can the state be exported without private browser data?
- Does the change add a new track when an existing token or phase would suffice?
- Does the change preserve a path to Return to Ocean?
- Has the change been recorded in the shared transition table?

## 9. Artifact discipline

- Keep canonical shared files in `shared/`.
- Keep WordPress-ready HTML in `cookieblob/`.
- Keep physical rules and component specifications in `game-crafter/`.
- Keep generated previews and temporary test files out of the public package unless they are deliberate deliverables.
- Use dated filenames for snapshots, not for files that are actively canonical.
- Increment the schema version when field meaning changes, not when prose changes.

## 10. First implementation target

The next build should create:

1. `shared/waterstorage-game-model.md`
2. `shared/waterstorage-seed-v1.schema.json`
3. `shared/transition-table-v0.1.md`
4. `shared/playtest-scenarios-v0.1.md`
5. `cookieblob/ROOM-ocean.html`
6. `cookieblob/ROOM-clouds.html`
7. `cookieblob/ROOM-precipitation.html`
8. `game-crafter/README.md`
9. `game-crafter/prototype-components-v0.1.md`
10. `game-crafter/rulesheet-v0.1.md`

Do not expand to all ten rooms or commission art until the three-phase vertical slice works in both interfaces.