# Open Decision Deck

A small, local workspace for decisions that deserve more than a chat reply.
An agent prepares cards with problems, recommendations, evidence, and open variables.
A person reviews them, then exports a build plan with the decisions attached.

This is a standalone public edition. It starts empty. The optional weekend-planner
example is entirely fictional. No service account, subscription, model API key,
or connection to an existing project management system is required.

## Start

Install Node.js 24.13 or newer. In this folder, run:

```sh
npm ci --ignore-scripts
npm start
```

Open **http://127.0.0.1:4387**. Stop with Ctrl+C. If the port is busy:

```sh
npm start -- --port 4388
```

There is no frontend build step. The same responsive browser interface works at
narrow widths. The server is intentionally bound to this computer's loopback
address; this release does not expose a phone-accessible or public service.

## A complete review

1. Choose **Try the example deck**, create an empty deck, or import a proposal JSON.
2. Read each problem, suggested course, evidence, and open variables. Choose a
   decision, add your response, and save. Unsaved browser drafts can be recovered.
3. Inspect **Build plan**. The agent supplies steps, acceptance criteria, source
   card IDs, and prerequisites. A simple draft helper is available for accepted cards.
4. Choose **Finish review**. Download the task bundle as JSON or Markdown.
5. Give the bundle to your agent or task system. Preserve the stable task IDs,
   project key, source decisions, and prerequisite links when importing it.

Accepted decisions become ready tasks when there are no prerequisites.
Unanswered decisions and requests for evidence block affected tasks. Deferred,
rejected, and already-resolved proposals are excluded. A dependent task stays
blocked until your execution system confirms its prerequisites are complete.
Accepted cards must be covered by the plan before finishing.

Keep reviews focused. The complete deck response, including repeated source
decisions and saved tasks, has a 4 MB limit. If a change exceeds it, split the
review, shorten the text, or reference fewer cards per step; nothing is saved.

Finish creates a portable task bundle; it does not send anything to another
service or start an agent. After any change, finish again before exporting current
tasks. Task IDs stay stable, so downstream integrations can update instead of
duplicating work. Historical bundles are snapshots; they cannot revoke work
already dispatched to another system.

## Agents

- **ChatGPT or Claude in a browser:** use the file exchange guide and prompt in
  [docs/agents.md](docs/agents.md). Import proposals and updates; export snapshots
  or finished tasks to return the human's answers.
- **Codex, Claude Code, or a local MCP client:** connect the included stdio MCP
  server. Six compact tools create/read decks, propose cards/plans, and read
  finished tasks. [Setup and configuration examples](docs/agents.md).
- **Reusable skill:** [skills/open-decision-deck/SKILL.md](skills/open-decision-deck/SKILL.md).
- **CLI:** `node cli.mjs --help`. All agent mutations require a UUID request ID;
  updates also require the current deck version.

No installation step changes your agent configuration. The skill and MCP setup
are opt-in and documented for the person installing the package.

## Storage and privacy

The application uses only its own `.decision-deck/deck.sqlite` beside this README.
It does not search for other applications, scan repositories, read home-directory
credentials, load `.env` files, or discover existing databases. To use another
location, explicitly set `OPEN_DECISION_DECK_DATA_DIR` to your chosen folder for
both the browser server and agent tools.

The app makes no outbound requests, loads no remote assets, and includes no
analytics or model calls. Installing dependencies contacts the npm registry.
Data is not encrypted at rest. Anyone with access to the local files has access
to the decks. See [SECURITY.md](SECURITY.md) for the trust boundary.

To back up your data, stop the browser server and all MCP/CLI writers, then copy
the entire `.decision-deck` folder to a private location. Restore into this
application's own data directory while all writers are stopped. JSON revision
downloads are readable audit snapshots, not database backups. Snapshot imports
are rejected so agent files cannot manufacture human approvals.

## Public release and development

```sh
npm test
npm run check:public
npm run release
```

The release command copies only files named in `release-files.json` into a new
folder under `.release/`, with a SHA-256 manifest. It excludes local decks,
exports, credentials, logs, installed dependencies, and version-control history.
Publish that generated folder. Once you have used the app, do not publish your
whole working directory: it may contain private decks or downloads.

`check:public` rejects unlisted source files, symlinks, common secret patterns,
personal filesystem paths, and unexpected network URLs. It is a useful gate,
not proof that arbitrary prose contains no sensitive information. All bundled
examples are synthetic. [Public release notes](docs/public-release.md).
The [security review](docs/security-review.md) records the checks and fixes made
before this reviewed release.

The code is MIT licensed. `private: true` prevents an accidental npm registry
publication; it does not restrict the source license. Dependencies retain their
own licenses. [Contributing](CONTRIBUTING.md).