# SOP — WaterStorage / Watershed Cross-Platform Build

**Version:** 0.1  
**Date:** 2026-07-17  
**Project:** WaterStorage, using the working name **Watershed** for the playable system  
**Outputs:** CookieBlob room + Game Crafter physical prototype  
**Public collection:** `waterstorage-cross-platform`

## 1. Purpose

Build one WaterStorage experience in two forms at the same time:

1. a CookieBlob room that teaches and records the system through interaction;
2. a Game Crafter prototype that makes the same transitions tangible at the table.

The two forms are companion interfaces to one hydrological information model, not separate games with drifting rules.

## 2. Source-of-truth hierarchy

1. The current WaterStorage framework and its phase definitions.
2. This SOP for cross-platform build procedure.
3. `parity-matrix.md` for stable IDs and shared state effects.
4. CookieBlob implementation files for browser presentation.
5. Game Crafter card, mat, and component files for physical presentation.

If the two implementations disagree, stop expansion, record the discrepancy in the parity matrix, and repair the shared rule before continuing.

## 3. Core design principles

- **Flow before spectacle:** Every interaction must show what moved, what held, or what became blocked.
- **Creeks before lakes:** Prefer small, reversible transitions before adding large reservoirs of rules or content.
- **Groundwater stays clean:** Keep state explicit, inspectable, and portable between formats.
- **The loop closes:** The end of a sequence should create a meaningful return toward the Ocean / basin system.
- **Revisit improves context:** A returning player receives a richer reading of the same state; prior trace is not silently erased.
- **Consequences are visible:** Scarcity, pollution, pressure, and blocked flow must be represented rather than hidden in prose.
- **Parity over symmetry:** The interfaces may differ in rhythm and materials, but a shared action must mean the same thing.

## 4. Canonical first slice

Implement only W01 and W02 before designing the complete deck.

### W01 — Ocean Acknowledged

- Browser: set the room to W01, append `W01` to trace, render the Ocean state.
- Table: place the shared marker on Ocean and record `W01`.
- State change: none.

### W02 — Evaporation

- Browser: if Ocean has a Flow unit, move one unit to Clouds; otherwise add Pressure and hold.
- Table: move one Flow token from Ocean to Clouds; otherwise add Pressure and hold.
- State change when successful: `flow -1`, `cloud +1`.
- State change when blocked: `pressure +1`.

This first slice is the acceptance test for the whole approach.

## 5. Folder contract

```text
watershed-cross-platform-public/
├── SOP-WATERSTORAGE-CROSS-PLATFORM-V0.1.md
├── CHANGELOG.md
├── parity-matrix.md
├── cookieblob/
│   ├── README.md
│   └── cookieblob-state-schema.json
└── game-crafter/
    ├── README.md
    └── phase-cards-v0.1.md
```

## 6. Paired build loop

For each new transition:

1. Choose the transition from the WaterStorage framework.
2. Assign a stable ID (`W03`, `W04`, and so on).
3. Define its starting conditions, visible action, success effect, blocked effect, and trace entry.
4. Add the row to `parity-matrix.md`.
5. Write the CookieBlob room text and state operation.
6. Write the Game Crafter card and component operation.
7. Test the same starting state in both formats.
8. Test the blocked path in both formats.
9. Test revisit behavior and trace persistence.
10. Update the changelog and sync the public collection.

Do not write the next transition until the current paired transition passes both tests.

## 7. CookieBlob implementation rules

- Keep all mutable values inside one versioned state object.
- Use a single load / save boundary around `localStorage`.
- Render the room from state after every action.
- Use stable IDs in buttons, traces, and exported transmissions.
- Include Reset only as an explicit, labeled development action.
- Keep the state schema compatible with the physical prototype’s counters.
- Escape or safely construct any user-entered transmission text before inserting it into the DOM.

## 8. Game Crafter implementation rules

- Print stable IDs on cards or card backs.
- Keep card text short enough to perform without consulting a separate essay.
- Use tokens for state that must be physically inspected during play.
- Put the basin zones on the mat, not only in the rules booklet.
- Provide a written trace area or trace card so a session can be transmitted back to CookieBlob.
- Prototype with paper before ordering manufactured parts.

## 9. Acceptance tests for v0.1

- A new user can describe the Ocean → Clouds movement after one browser action and one table action.
- W02 succeeds identically when Flow is available.
- W02 blocks identically when Flow is unavailable.
- The blocked result is visible and adds Pressure.
- W01 and W02 IDs appear in the trace.
- Reloading the CookieBlob room retains state and trace.
- A physical session can be recorded in a form that maps back to the same IDs.
- The parity matrix contains no unexplained disagreement.

## 10. Publishing procedure

From `/home/workspace`:

```bash
zopub sync waterstorage-cross-platform /home/workspace/WaterStorage/watershed-cross-platform-public
```

After every sync, verify the collection listing and report:

`https://zo.pub/tenchi/waterstorage-cross-platform`

## 11. Next build step

Create the paired W01/W02 CookieBlob room and a printable basin mat. Do not design W03 until the first slice has been played once in each format and the parity matrix has been checked.