dreamboard 0.1.21 → 0.1.23

package/skills/dreamboard/references/boards-and-topology.md

@@ -1,100 +0,0 @@
-# Boards and topology
-
-Model generic, hex, and square boards with typed spaces, edges, vertices, containers, and board refs.
-
-Boards are manifest-defined topology. They can be generic, hex, or square, shared or per-player, inline or based on a template.
-
-## Board layouts
-
-| Layout | Use for |
-| --- | --- |
-| `generic` | Free-form spaces and relations, tracks, maps, abstract zones. |
-| `hex` | Hex grids with spaces, edges, and vertices. |
-| `square` | Square grids with rows, columns, spaces, edges, and vertices. |
-
-All layouts can have spaces and containers. Tiled layouts also expose typed edge and vertex ids.
-
-## Inline board
-
-```ts
-boards: [
-  {
-    id: "action-board",
-    name: "Action Board",
-    layout: "square",
-    scope: "shared",
-    spaces: [
-      { id: "plaza", row: 0, col: 0, typeId: "action" },
-    ],
-  },
-];
-```
-
-Use inline boards when a board appears once. Use templates when several board instances share topology.
-
-## Templates
-
-```ts
-boardTemplates: [
-  {
-    id: "market-template",
-    name: "Market Template",
-    layout: "generic",
-    spaces: [
-      { id: "auction", typeId: "action" },
-      { id: "harvest", typeId: "action" },
-    ],
-  },
-],
-boards: [
-  {
-    id: "market-board",
-    name: "Market Board",
-    templateId: "market-template",
-    layout: "generic",
-    scope: "shared",
-  },
-];
-```
-
-Template-backed boards still get their own board id. Reducer and UI code should address runtime board data by board id, not by template id.
-
-## Shared and per-player boards
-
-`scope: "shared"` creates one board instance for the session. `scope: "perPlayer"` creates one board per player.
-
-Use shared boards for central maps and markets. Use per-player boards for player mats, personal tracks, and private layouts.
-
-## Runtime board queries
-
-Inside reducer callbacks, views, derived values, and target rules, read board data through injected `q`:
-
-```ts
-const board = q.board.hex("island");
-const edge = q.board.edge("island", edgeId);
-const adjacent = q.board.incidentVertices("island", edgeId);
-```
-
-Use `q.board.get` for layout-agnostic access, `q.board.hex` / `q.board.square` for layout-specific topology, and traversal helpers such as `incidentEdges`, `incidentVertices`, `spaceEdges`, `spaceVertices`, and `squareNeighbors` for rules.
-
-## Static board projection
-
-Static board topology belongs in [Static views](./static-views.md), not in dynamic player views.
-
-```ts
-export const boardStatic = defineStaticView<GameContract>()({
-  project: ({ q }) => {
-    const board = q.board.hex("island");
-    return {
-      ...board,
-      portsByVertexId: computePorts(board),
-    };
-  },
-});
-```
-
-Keep game-specific decoration local, but use SDK static board queries for reusable topology access.
-
-## Deep topology reference
-
-For exact square/hex edge and vertex id rules, see [Board topology](./board-topology.md).

package/skills/dreamboard/references/card-actions.md

@@ -1,107 +0,0 @@
-# Card actions
-
-Use defineCardAction for first-class actions that play a card from a hand zone.
-
-Use `defineCardAction` when the player action starts from a concrete card in a hand or card zone: play an action card, reveal a tactic, discard a reaction, trigger a card ability.
-
-```ts
-import { cardTypes, zones } from "../shared/manifest-contract";
-
-const playBoost = defineCardAction<
-  GameContract,
-  typeof playerTurnPhaseStateSchema
->()({
-  cardType: cardTypes.boost,
-  playFrom: zones.actionHand,
-  label: "Play boost",
-  step: "main",
-  inputs: {
-    selectedSpaceId: boardInput.space<GameState, SpaceId>({
-      target: selectableSpaceTarget,
-    }),
-    stealFromPlayerId: formInput(ids.playerId.nullable()),
-  },
-  rules: [
-    {
-      id: "can-play-action-card",
-      errorCode: "CARD_NOT_PLAYABLE",
-      validate: ({ state }) => validateCanPlayActionCard(state),
-    },
-  ],
-  reduce({ state, input, accept, ops }) {
-    return accept(
-      pipe(
-        state,
-        ops.moveCardFromPlayerZoneToSharedZone({
-          playerId: input.playerId,
-          fromZoneId: zones.actionHand,
-          toZoneId: zones.playedCards,
-          cardId: input.params.cardId,
-          playedBy: input.playerId,
-        }),
-        ops.patchPublicState({ selectedSpaceId: input.params.selectedSpaceId }),
-      ),
-    );
-  },
-});
-```
-
-## How it differs from defineInteraction
-
-`defineCardAction` supplies the card-specific contract:
-
-| Field | Meaning |
-| --- | --- |
-| `cardType` | Manifest card type that can trigger this action. |
-| `playFrom` | Manifest player zone id the card must be playable from. |
-| `inputs` | Additional params besides the selected card. |
-| `step` / `steps` | Optional phase-step gates, typed from `state.phase.step` when your phase state schema declares a string literal union. |
-| `rules` | Card-specific availability and validation, often shared across a family of cards. |
-| `cost` / `paramsSchema` / `commit` | Same interaction metadata as `defineInteraction`, when the card action needs affordability, cross-field params, or manual draft control. |
-| `reduce` | Receives `input.params.cardId` automatically. |
-
-The generated interaction contract treats card actions as card-anchored
-interactions. `Zone` plus `Interaction.CardInput` can show a playable card and
-collect additional inputs without each workspace inventing local card-action
-plumbing.
-
-Card actions are always card-anchored interactions. Use `defineInteraction` for
-non-card commands and group them visually in React.
-
-## Zone-backed rendering
-
-Declare the hand zone once in the phase:
-
-```ts
-zones: [zones.actionHand],
-cardActions: {
-  playBoost,
-  playDrawCards,
-  playBuildPath,
-},
-```
-
-The reducer projection is keyed by the manifest zone id, such as `action-hand`.
-Import `zones` and `cardTypes` from the generated manifest contract so authoring
-code uses typed handles instead of raw string ids. Cards come from the listed
-manifest player zone; playable descriptors are derived from `cardActions` whose
-`playFrom` matches that zone.
-
-## Validation
-
-Target validation still runs before authored rules. Use `rules` for
-card-specific business checks: once per turn, bought this turn, enough
-resources, correct phase step, or no pending trade.
-
-Move the card in `reduce`. `defineCardAction` makes the card id available; it does not decide whether the card should be discarded, trashed, returned, tucked, or left in play.
-
-## When to use defineInteraction instead
-
-Use `defineInteraction` when:
-
-- the action is not tied to a card instance
-- the player chooses from a board target, form, or panel button first
-- a prompt asks for a response
-- the card is only one optional input among several unrelated choices
-
-Use `defineCardAction` when the card is the object being played.

package/skills/dreamboard/references/cli.md

@@ -1,120 +0,0 @@
-# CLI
-
-Reference for Dreamboard CLI workflows and commands.
-
-Dreamboard CLI manages the authored workspace loop: authenticate, create or
-clone a game, sync authored changes, compile, develop, and test.
-
-## What the CLI does
-
-Use the CLI for:
-
-- authenticating the current machine
-- creating or cloning game workspaces
-- syncing authored files to the remote authoring head
-- compiling the current authored head
-- inspecting local versus remote state
-- pulling remote authored changes into the workspace
-- starting a local dev server to play the game in the browser
-- generating and running reducer-native tests
-
-## Install targets
-
-Use the published package for normal game work:
-
-```bash
-npm install -g dreamboard
-dreamboard login
-```
-
-## Command flow
-
-Use this sequence for the normal authored loop:
-
-1. `dreamboard login`
-2. `dreamboard new ...` or `dreamboard clone ...`
-3. edit `rule.md`, `manifest.ts`, and authored source files
-4. `dreamboard sync`
-5. `dreamboard compile`
-6. `dreamboard dev` (play in browser)
-7. `dreamboard test generate` (after reducer/manifest shape changes)
-8. `dreamboard test run` (automated tests)
-
-When the remote authored head moves first, run `dreamboard pull` before the
-next sync or compile. Use `dreamboard status` to decide whether the workspace is
-ahead, behind, or diverged.
-
-## Workspace commands
-
-| Command | Use it for |
-| --- | --- |
-| `dreamboard login` | Open browser login and store a refreshable session |
-| `dreamboard new <slug> --description "..."` | Create a new game and scaffold a local workspace |
-| `dreamboard clone <slug>` | Clone an existing game into a new local workspace |
-| `dreamboard config show` | Inspect resolved CLI, backend, compiler, and workspace config |
-| `dreamboard sync` | Upload authored changes and refresh scaffolded files |
-| `dreamboard compile` | Compile the current remote authored head |
-| `dreamboard status` | Compare local authored and compile state with remote |
-| `dreamboard pull` | Reconcile remote authored changes into the workspace |
-| `dreamboard join --player <id>` | Join a playable session as a bot or local player helper |
-
-```bash
-dreamboard new race-to-ten --description "A tiny scoring game"
-dreamboard sync
-dreamboard compile
-dreamboard status --json
-```
-
-`dreamboard sync` also reconciles local workspace dependencies when `package.json`
-changes, so users should not run a separate install command as part of the
-normal authored workflow.
-
-The CLI materializes `.dreamboard/generated/manifest.json` from `manifest.ts`
-for local tooling. Treat that file as generated output, not authored source.
-
-## Authentication storage
-
-`dreamboard login` stores a refreshable session on the current machine.
-By default the CLI writes credentials to the operating system keychain
-(Keychain on macOS, Credential Vault on Windows, Secret Service on
-Linux), so the refresh token is encrypted at rest and is not readable
-by other tools that scan the home directory.
-
-If the native keyring is unavailable (for example in a container
-without libsecret) the CLI falls back to `~/.dreamboard/auth.json`
-owned by the current user. You can pin a specific backend with:
-
-```bash
-# Force the file-based backend even when the OS keychain is available.
-export DREAMBOARD_CREDENTIAL_BACKEND=file
-```
-
-Run `dreamboard config show` to inspect which API endpoint and workspace
-configuration the CLI resolved.
-
-Credentials are only rewritten after a successful token rotation.
-Transient errors during `dreamboard sync` or `dreamboard compile` no
-longer clear the stored refresh token, so a network hiccup will not
-force you to log in again. If you ever need to start fresh, run
-`dreamboard logout` or `dreamboard auth clear` to wipe the session
-explicitly.
-
-## Dev server
-
-Start a local server to play the compiled game in the browser:
-
-```bash
-dreamboard dev
-```
-
-## Test commands
-
-Use the scaffolded reducer-native test workspace for repeatable game assertions.
-
-```bash
-dreamboard test generate
-dreamboard test run
-dreamboard test run --scenario test/scenarios/player-two-wins.scenario.ts
-```
-
-See [Testing](./testing.md) for the scenario and base-file format.