Metadata-Version: 2.4
Name: ghost-reader
Version: 0.2.0
Summary: Persona-driven fiction review simulator CLI
Author-email: Kevin Chin <kevin@kevindchin.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/clchinkc/ghost-reader
Project-URL: Repository, https://github.com/clchinkc/ghost-reader
Project-URL: Documentation, https://github.com/clchinkc/ghost-reader/blob/main/agent-setup.md
Keywords: fiction,beta-reader,writing,feedback,review,persona
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: General
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0.2
Requires-Dist: jinja2>=3.1.6
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Dynamic: license-file

# Ghost Reader CLI

Local-first persona-driven fiction review simulator for structured beta-reader-style feedback.

[![PyPI version](https://img.shields.io/pypi/v/ghost-reader)](https://pypi.org/project/ghost-reader/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**Repository:** https://github.com/clchinkc/ghost-reader

## For AI agents

Agents with web fetch and shell access should start here:

1. Fetch [agent-setup.md](agent-setup.md) (short bootstrap; do not scrape HTML report templates).
2. Install [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/), then install from PyPI:

```bash
uv tool install ghost-reader
# or: pipx install ghost-reader
ghost-reader help
ghost-reader update check
```

3. Install the skill: copy `skills/ghost-reader/` into your harness skill directory, or invoke `Skill(ghost-reader)` when available.
4. Read the operational contract: [skills/ghost-reader/SKILL.md](skills/ghost-reader/SKILL.md) (workflow) and [skills/ghost-reader/reference.md](skills/ghost-reader/reference.md) (data model, Phase 3 roadmap).

## Documentation map

| Document | Audience | Role |
|----------|----------|------|
| [agent-setup.md](agent-setup.md) | Agents | Bootstrap, install, 11-step workflow |
| [skills/ghost-reader/SKILL.md](skills/ghost-reader/SKILL.md) | Agents | Operational contract |
| [skills/ghost-reader/reference.md](skills/ghost-reader/reference.md) | Agents | Schemas, paths, HTTP API |
| [llms.txt](llms.txt) | Agents | Command index |
| [examples/README.md](examples/README.md) | Everyone | Canonical sample trace (committed) |
| [AGENTS.md](AGENTS.md) / [CLAUDE.md](CLAUDE.md) | Harness | Pointers to the above |

The CLI remains local-first and binds `serve` to `127.0.0.1` by default. An optional,
account-free Vercel deployment can serve Supabase-backed sessions by share URL.

## Current status (Phase 2.5)

- Local CLI with iterative refinement rounds (`round init`, `refine snapshot`).
- Structured YAML for personas, reviews, feedback, and revision prompts.
- Local HTML reports from `report/payload.json` and swappable templates.
- Bidirectional feedback via `ghost-reader serve` (`POST /api/feedback`, `/api/dialogue`).
- Persona dialogue (`dialogue append`, `dialogue context`).
- Content-safe local telemetry and local sync bundles.
- Optional Supabase session storage selected with `GHOST_READER_STORAGE=supabase`.
- Public, telemetry-disabled Vercel report serving with `?session=<id>` routing.
- Verification statuses (per session): `review_ready_feedback_pending` → `refinement_complete` → `phase1_complete` (these are **verify** outputs, not separate product phases).

Artifact contracts: review and feedback **schema v2 only**; sessions use **round-*** directories (no flat legacy layout).

There are no hosted user accounts or authentication. Phase 3 persona recommendation is
**planned** (not in the CLI yet); see roadmap below.

## Share a report through Vercel

The authoring CLI writes directly to Ghost Reader's dedicated Supabase project; the deployed server is a
read/write presentation layer over the same session. Keep the service-role key on trusted
authoring machines and in Vercel environment variables only.

```bash
cd /path/to/your-story-project
export GHOST_READER_STORAGE=supabase
export GHOST_READER_PROJECT_ID=your-project-id
export SUPABASE_URL=https://your-project.supabase.co
export SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

ghost-reader init
session_id="<unguessable-session-id>"
ghost-reader session create --id "$session_id" --story-unit "chapter 3" --personas mara,dex,pip
ghost-reader artifact write --session "$session_id" --type source-text --from chapter-3.md
# Write the persona review artifacts, then render:
ghost-reader render --session "$session_id"
```

Share `https://ghost-reader-six.vercel.app/?session=<session-id>`. The deployed server has
no login: anyone who receives a session URL can access that report. Use non-guessable
session IDs for material that is not intended for broad discovery.

Deployment uses an isolated `ghost_reader` Supabase schema in the dedicated Ghost Reader
project. Telemetry is disabled in the container, and personas and templates are packaged
in the image.

The Vercel project requires `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`,
`GHOST_READER_PROJECT_ID`, and a default `SESSION_ID`. Vercel injects `PORT`. Container
startup fails immediately if `SESSION_ID` or `PORT` is missing.

## For Writers (human users)

Ghost Reader is designed for writers who want structured, persona-driven feedback on their drafts. You don't need to be an AI expert — the CLI handles everything.

**Typical workflow (10 minutes):**

```bash
# 1. Install once
uv tool install ghost-reader

# 2. Go to your story project
cd ~/writing/my-novel

# 3. Initialize Ghost Reader
ghost-reader init

# 4. Create a review session for a chapter
ghost-reader session create --id chapter-3 --personas mara,dex,pip

# 5. Have your AI assistant (Claude, ChatGPT, etc.) write review YAMLs
#    Give it this prompt: "Read the attached chapter and write a Ghost Reader
#    review as the Mara persona. Use schema v2. Save as mara.review.yaml."
#    (Repeat for Dex and Pip.)

# 6. Load the reviews into Ghost Reader
ghost-reader artifact write --session chapter-3 --type review --persona mara --from mara.review.yaml
ghost-reader artifact write --session chapter-3 --type review --persona dex --from dex.review.yaml
ghost-reader artifact write --session chapter-3 --type review --persona pip --from pip.review.yaml

# 7. Render the interactive report
ghost-reader render --session chapter-3

# 8. Open it in your browser
ghost-reader serve --session chapter-3
```

The report shows each persona's findings side-by-side with cited passages, severity ratings, and specific revision suggestions. You can select which items to address and export a revision prompt to guide your next rewrite.

**No AI assistant?** You can also write review YAMLs manually — see the schema reference in [skills/ghost-reader/reference.md](skills/ghost-reader/reference.md). But Ghost Reader works best paired with an LLM that generates the structured reviews.

**Key concept**: Ghost Reader is the *review management system*. The AI generates the reviews. Ghost Reader renders, verifies, and tracks them — giving you a structured feedback loop instead of scattered chat responses.

## Install (users)

Requires Python 3.11+. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) or [pipx](https://pipx.pypa.io/) first.

| Method | Command |
|--------|---------|
| **uv tool** (recommended) | `uv tool install ghost-reader` |
| **pipx** | `pipx install ghost-reader` |
| **uvx** (no global install) | `uvx ghost-reader help` |
| **Dev (clone)** | `git clone git@github.com:clchinkc/ghost-reader.git && cd ghost-reader && uv sync --extra dev` then `uv run ghost-reader help` |

`uv tool install` places `ghost-reader` on your PATH (typically `~/.local/bin`).

```bash
ghost-reader init   # run from your story project directory
ghost-reader help
```

### Build wheel locally

```bash
uv build
uv tool install dist/*.whl
```

### Version management

Published to [PyPI](https://pypi.org/project/ghost-reader/) via OIDC trusted publishing. Version is set in `pyproject.toml` and released with a `v*` git tag. Run `ghost-reader update check` to compare the installed version against PyPI.

## Sample trace

The repo includes a full **review_ready_feedback_pending** example at [examples/sample-trace/](examples/sample-trace/). See [examples/README.md](examples/README.md).

```bash
cd examples/sample-trace
export GHOST_READER_HOME="$PWD/.ghostreader-home"
ghost-reader init
ghost-reader verify --session chapter-1
ghost-reader serve --session chapter-1
```

Regenerate after contract changes: `uv run python scripts/refresh_sample_trace.py`

## Quick workflow

Run all commands from the **story project directory** (where `.ghostreader/` lives), not from a clone of this repo unless you are developing Ghost Reader itself.

```bash
cd /path/to/your-story-project
ghost-reader init
ghost-reader session create --id chapter-3 --story-unit "chapter 3" --personas mara,dex,pip
# LLM writes review YAML per persona, then:
ghost-reader artifact write --session chapter-3 --type review --persona mara --from mara.review.yaml
ghost-reader render --session chapter-3
ghost-reader verify --session chapter-3
ghost-reader serve --session chapter-3 --timeout 600
```

After reviews render, **`serve` is the primary user path**: the user selects items in the browser and clicks **Submit Feedback**, which writes `feedback/feedback.yaml`. The agent then polls `ghost-reader feedback summary --session chapter-3`, runs `ghost-reader prompt revision`, rerenders, and verifies `phase1_complete`.

If `serve` is unavailable, open `file://` on `.ghostreader/sessions/<id>/round-<n>/report/index.html` and use the copy-paste **Ghost Reader Prompt** fallback.

### Pasted text (no story repo yet)

```bash
mkdir -p ~/ghost-reader-projects/my-chapter
cd ~/ghost-reader-projects/my-chapter
export GHOST_READER_HOME="$PWD/.ghostreader-home"
ghost-reader init
ghost-reader session create --id ch1 --story-unit "chapter 1"
```

Use `/tmp/ghost-reader-*` only for disposable tests.

### Developer setup (this repo)

```bash
git clone git@github.com:clchinkc/ghost-reader.git
cd ghost-reader
uv sync --extra dev
uv run ghost-reader update check

cd /path/to/story-project
uv run --project /path/to/ghost-reader --no-editable ghost-reader init
```

## Report design contract

- Source text stays readable; annotations tie to cited passages.
- Full reader reasons live in persona sections, not only tooltips.
- Quiet, dense layout; no marketing-style chrome.

## Test

```bash
uv lock --check
uv run --with ruff ruff check .
uv run --with pytest pytest
```

## Code structure

| Module | Role |
|--------|------|
| `cli.py` | Command surface |
| `server.py` | Local bidirectional HTTP (`serve`) |
| `feedback_store.py` | Shared feedback persist + telemetry |
| `validators.py` | Artifact contracts |
| `report.py` | HTML from `payload.json` |
| `verify.py` | Session gates |
| `telemetry.py` / `sync.py` | Local events and export bundles |
| `storage/` | Local and Supabase session persistence |

## Roadmap: Phase 3 (planned)

Persona recommendation as a spatial HTML comparison artifact (`recommendation.html`) and `ghost-reader recommend` are **not implemented yet**. Until then, users choose personas manually (`mara`, `dex`, `pip`, or optional `elena`, `rook`). Custom personas are created by LLMs through the Ghost Reader skill — no CLI import command. Design notes: [skills/ghost-reader/reference.md](skills/ghost-reader/reference.md#phase-3-persona-recommendation-planned).
