> ## Documentation Index
> Fetch the complete documentation index at: https://docs.highailabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notebook Studio

> Run and use the browser-based Notebook Studio to prototype notebooks, research states, lifecycle behavior, and immutable updates without the mobile app.

# Notebook Studio

Notebook Studio is the canonical local prototyping surface for the paid notebook experience. It runs in a browser, uses synthetic fixtures, and composes the same first-party Report V2 engine used by the production code path.

It does not require Expo, a simulator, Clerk, Convex, Supabase, a provider API key, or customer data.

<Info>
  Studio is a design and deterministic contract tool. It does not prove native sheets, gestures, haptics, safe areas, app backgrounding, or real provider behavior. Those need separate device and staging certification.
</Info>

## Start Studio

From the repository root:

```bash theme={null}
pnpm install --frozen-lockfile
pnpm turbo build --filter="./packages/*"
pnpm --filter @highiq/mobile storybook:studio
```

Open:

```text theme={null}
http://127.0.0.1:6006/?path=/story/notebooks-studio--primary
```

The shared-package build matters. Mobile imports `@tiwih/*` packages from their generated `dist` output; stale output can make a valid source change look missing at runtime or during typecheck.

## Ten panels

| Panel                          | Use it to answer                                                                                |
| ------------------------------ | ----------------------------------------------------------------------------------------------- |
| **User Journey**               | Does the full notebook communicate value and a clear next action?                               |
| **Order & Matching**           | Were every recorded line, alias, ambiguity, duplicate, and unit preserved correctly?            |
| **Research Pipeline**          | Are fresh, stale, conflicting, missing, failed, and timed-out states honest?                    |
| **Versions & Updates**         | Can the user compare, request, cancel, retry, promote, and revisit immutable versions?          |
| **Source Snapshot**            | Does the minimized frozen input contain everything required and nothing private or operational? |
| **Lessons & Evidence**         | Does each claim point to valid recorded or research evidence?                                   |
| **Media Lab**                  | Which deterministic inputs are ready, and which companion executors remain blocked?             |
| **Lifecycle**                  | What happens at each generation, minimize, background, cancel, retry, and supersession event?   |
| **Entitlement**                | Is the free preview distinct from paid account generation?                                      |
| **Validation & Accessibility** | Do payload, privacy, evidence, touch-target, and reduced-motion checks pass?                    |

Panel and scenario selections are stored in the URL as `studioPanel` and `studioScenario`, so a specific proposal can be shared as a deterministic deep link.

## Scenario matrix

Studio currently provides 29 scenarios.

| Group             | Scenarios                                                                                                          |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| Matching          | Known strain, known plus unknown, all unknown, alias, ambiguous, placeholder, duplicate lines                      |
| Order boundaries  | Mixed units, missing price, missing dispensary, 32-line order, payload pressure                                    |
| Research          | Fresh, stale, conflicting sources, no research, timeout, failure and retry                                         |
| Immutable updates | Update available, update generating, update promoted                                                               |
| Lifecycle         | Superseded run, cancel during preparing/research/generation/finalization, cancel too late, close/background/reopen |
| Entitlement       | Free preview and paid generation                                                                                   |

Use the pairwise matrix instead of checking only the known-strain happy path. At minimum, every change should compare:

* one happy path;
* one unknown or ambiguous input;
* one stale or failed research state;
* one cancellation or recovery state;
* one immutable update state;
* free and paid entitlement behavior;
* a long or payload-pressure boundary.

## Recommended review loop

<Steps>
  <Step title="State the product question">
    Example: “How should an unknown strain appear while research is pending?” or “What remains readable if an update fails?”
  </Step>

  <Step title="Choose the nearest fixture">
    Start with a built-in scenario. Avoid changing production data just to explore a design question.
  </Step>

  <Step title="Inspect every affected panel">
    Review the user journey, matching, research, lessons/evidence, lifecycle, and validation panels—not only the final card.
  </Step>

  <Step title="Compare adjacent states">
    Check before, during, successful, failed, canceled, and retry states. For updates, compare current, update available, generating, promoted, and history.
  </Step>

  <Step title="Export or deep-link the proposal">
    Use Studio's bounded fixture export or copy the deep link. Never import production customer records or secrets.
  </Step>

  <Step title="Lock accepted behavior in code">
    Update the shared engine or fixture contract, add a deterministic test, and rerun the browser interaction and static build gates.
  </Step>
</Steps>

## Safe fixture rules

* Use synthetic names, orders, URLs, and evidence.
* Do not paste emails, account IDs, addresses, phone numbers, receipts, tokens, provider payloads, or raw production database rows.
* Preserve explicit `null` or unavailable values; do not replace them with plausible defaults.
* Keep research URLs synthetic unless the fixture is specifically testing a public-source parser.
* Treat fixture import as untrusted input; validation must pass before rendering.

## Verification commands

Run these after changing Studio, the shared notebook engine, or Report V2 contracts:

```bash theme={null}
pnpm --filter @tiwih/report-contracts test
pnpm --filter @tiwih/report-contracts typecheck
pnpm --filter @tiwih/notebook-engine test
pnpm --filter @tiwih/notebook-engine typecheck
pnpm turbo build --filter=@tiwih/report-contracts --filter=@tiwih/notebook-engine
pnpm --filter @highiq/mobile test:storybook
pnpm --filter @highiq/mobile typecheck:storybook
pnpm --filter @highiq/mobile lint:storybook
pnpm --filter @highiq/mobile build:storybook
```

For a broader release-quality change, also run the full mobile unit, Convex, UI, typecheck, lint, design-system, and geometry gates documented in [Notebook launch runbook](/planning/notebooks/launch-runbook).

## What Studio can and cannot certify

| Claim                                       | Studio | Additional proof required                   |
| ------------------------------------------- | ------ | ------------------------------------------- |
| Deterministic payload and evidence mapping  | Yes    | Contract/unit tests                         |
| Unknown and stale research presentation     | Yes    | Staging data integration                    |
| Immutable version comparison                | Yes    | Convex owner/read/promotion tests           |
| Browser accessibility and responsive layout | Yes    | Static Storybook plus browser checks        |
| Native progress sheet and accessory         | No     | Argent/Revyl/manual device run              |
| Background execution on iOS                 | No     | Real app lifecycle proof                    |
| Provider output quality and cancellation    | No     | Provider sandbox evaluation                 |
| Hosted migration correctness                | No     | Approved disposable/canonical database lane |

## Troubleshooting

<AccordionGroup>
  <Accordion title="A new shared export is undefined">
    Rebuild `@tiwih/report-contracts` and `@tiwih/notebook-engine`. The mobile app consumes built workspace packages, not their source files directly.
  </Accordion>

  <Accordion title="Port 6006 is already in use">
    Stop the existing local Storybook process or use the already running instance. Do not start multiple Studio servers against different branches and assume they show the same code.
  </Accordion>

  <Accordion title="A fixture renders as unavailable">
    Check the Validation panel first. Historical or imported content intentionally fails closed when its safe Report V2 projection is incomplete.
  </Accordion>

  <Accordion title="Studio looks correct but the app differs">
    Treat that as an integration or native-certification gap. Record the scenario and run the equivalent app flow; do not weaken the shared contract to match an accidental mobile behavior.
  </Accordion>
</AccordionGroup>

## Related documentation

* [Notebook program overview](/planning/notebooks/overview)
* [Research and generation](/planning/notebooks/research-generation)
* [Notebook launch runbook](/planning/notebooks/launch-runbook)