npm package: @owenbush/decodie-ui
Description: Presentation layer for Decodie
Latest version: 1.4.0

<p align="center"><img src="assets/decodie-logo.png" alt="Decodie" width="200"></p>

# Decodie UI

A browsable, filterable interface for exploring learning entries generated by the [decodie-skill](https://github.com/owenbush/decodie-skill) during coding sessions.

## Features

- **Structured lessons** -- entries are automatically grouped into topic-based lessons, sorted by difficulty. Create custom lessons with ordering and per-entry notes.
- **Progress tracking** -- mark entries as learned and track progress through each lesson with visual indicators.
- **Sequential navigation** -- step through lessons entry by entry with next/previous controls and a sidebar outline.
- **Smart filtering** -- filter by experience level, topic, decision type, session, and lifecycle. Switch between lesson and entry views.
- **Interactive Q&A** -- highlight text and ask follow-up questions via LLM-powered chat with conversation persistence.
- **Code references** -- content-based anchoring that survives refactoring.
- **Syntax highlighting** -- code displayed alongside explanations.
- **External doc links** -- automatic links to php.net, MDN, framework docs, etc.

## Prerequisites

- Node.js 18+

## Quick Start

Run directly from npm without installing:

```bash
npx @owenbush/decodie-ui serve --dir /path/to/project
```

This starts the server pointing at a project directory that contains a `.decodie/` folder. Open `http://localhost:8081`.

## Install the Commands

The Decodie commands for Claude Code can be installed with a single command:

```bash
npx @owenbush/decodie-ui install-skill
```

This downloads the command files from the [decodie-skill](https://github.com/owenbush/decodie-skill) repo into `~/.claude/commands/decodie/`, giving you:

- `/decodie:observe` — Document decisions as you code
- `/decodie:analyze` — Analyze existing code retroactively
- `/decodie:ask` — Ask questions about entries

To install at project level instead (shared with your team):

```bash
npx @owenbush/decodie-ui install-skill --scope project
```

## Development

```bash
git clone https://github.com/owenbush/decodie-ui.git
cd decodie-ui
npm install
npx tsx src/cli.ts serve --dir /path/to/project
```

## Production

```bash
npm run build
node dist/cli.js serve --dir /path/to/project
```

## Q&A Setup

Q&A lets you ask follow-up questions about any learning entry. Credentials are stored in `.decodie/.env` (not tracked by git). Set one of the following:

- **`CLAUDE_CODE_OAUTH_TOKEN`** -- uses your Claude Pro/Max subscription (run `claude setup-token` to obtain a token).
- **`CLAUDE_API_KEY`** -- pay-per-token billing (get a key at [console.anthropic.com](https://console.anthropic.com/)).

The **Settings** page in the UI shows setup instructions.

## Conversation Persistence

Q&A conversations are saved to `.decodie/conversations/` as JSON files (one per entry) and persist across sessions. Revisit any entry to pick up where you left off.

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/status` | Service health and entry statistics |
| GET | `/api/entries` | List entries with filtering support |
| GET | `/api/entries/:id` | Get a single entry with full content |
| PATCH | `/api/entries/:id` | Update entry fields (lifecycle, pinned) |
| GET | `/api/config` | Read user configuration |
| GET | `/api/lessons` | List all lessons (auto-generated + custom) |
| GET | `/api/lessons/:id` | Get lesson detail with ordered entries |
| POST | `/api/lessons` | Create a custom lesson |
| PUT | `/api/lessons/:id` | Update a custom lesson |
| DELETE | `/api/lessons/:id` | Delete a custom lesson |
| GET | `/api/progress` | Get progress data (learned entries) |
| POST | `/api/progress/:entryId/learn` | Mark an entry as learned |
| DELETE | `/api/progress/:entryId/learn` | Unmark an entry as learned |
| GET | `/api/qa/status` | Check whether Q&A is enabled |
| POST | `/api/qa` | Ask a question about an entry (SSE stream) |
| GET | `/api/conversations` | List entry IDs that have saved conversations |
| GET | `/api/conversations/:entryId` | Get a saved conversation |
| PUT | `/api/conversations/:entryId` | Save or update a conversation |
| DELETE | `/api/conversations/:entryId` | Delete a saved conversation |

## Tests

```bash
npm test
```

## Data Format

The `.decodie/` directory structure and JSON schemas are defined in the [decodie-skill](https://github.com/owenbush/decodie-skill) repository under `schema/`.

## Related Repositories

- [owenbush/decodie](https://github.com/owenbush/decodie) -- Main site and documentation.
- [owenbush/decodie-skill](https://github.com/owenbush/decodie-skill) -- The skill that generates `.decodie/` data during coding sessions.
- [owenbush/decodie-ddev](https://github.com/owenbush/decodie-ddev) -- DDEV add-on that serves this UI as a DDEV service.
- [owenbush/decodie-vscode](https://github.com/owenbush/decodie-vscode) -- VSCode extension with sidebar entry browser and right-click analysis. [Install from Marketplace](https://marketplace.visualstudio.com/items?itemName=owenbush.decodie-vscode).
- [owenbush/decodie-core](https://github.com/owenbush/decodie-core) -- Shared data layer used by this UI and the VSCode extension.