ghost-reader 0.0.1__tar.gz

ghost_reader-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Chin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ghost_reader-0.0.1/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: ghost-reader
+Version: 0.0.1
+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 :: 3 - Alpha
+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: 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)
+
+**Source:** 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/) if needed, then install the CLI from `main`:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv tool install 'git+ssh://git@github.com/clchinkc/ghost-reader.git'
+ghost-reader help
+ghost-reader update check
+```
+
+Requires access to the private repo (SSH key or `gh auth login` for HTTPS git URLs).
+
+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 |
+
+No hosted web service, no authentication server, no API keys. The `serve` command binds to `127.0.0.1` only — local-first by design.
+
+## Current status (Phase 2)
+
+- 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.
+- 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).
+
+No hosted web app. Phase 3 persona recommendation is **planned** (not in the CLI yet); see roadmap below.
+
+## Install (users)
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) first.
+
+| Method | Command |
+|--------|---------|
+| **pipx** (recommended) | `pipx install ghost-reader` |
+| **uv tool** (recommended) | `uv tool install ghost-reader` |
+| **uvx** (no install) | `uvx ghost-reader help` |
+| **Git (private repo)** | `uv tool install 'git+ssh://git@github.com/clchinkc/ghost-reader.git'` |
+| **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`).
+`pipx install` places it in a pipx-managed virtualenv.
+
+```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 via OIDC trusted publishing on `git tag v*`. The version in `pyproject.toml` is the single source of truth — keep it in sync with `src/ghost_reader/__init__.py` and `src/ghost_reader/.release-version`.
+
+## 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 |
+
+## Roadmap
+
+### Phase 1 — local CLI (shipped)
+Local-first persona-driven review, structured YAML, HTML report, validation gates.
+
+### Phase 2 — iterative rounds (shipped)
+Multi-round workflow, dialogue with personas, bidirectional serve UI, content-safe telemetry, local sync bundle. See [skills/ghost-reader/SKILL.md](skills/ghost-reader/SKILL.md).
+
+### Phase 2.5 — CLI feedback-loop extension (planned, doc-first)
+Extend the existing CLI loop (`serve` → `feedback add/summary` → `prompt revision`) for future remote-catalog sync without breaking local-first operation. Outbound: content-safe events + selected persona IDs + acted-on feedback categories + catalog refs + recommendation receipts. Inbound: catalog metadata + recommendation candidates + receipt IDs. **Raw story text never syncs by default.** No new command surface in this phase — `sync` is extended in docs first, then code.
+
+### Phase 3 — hosted option + remote catalog + recommendation engine (planned)
+Persona recommendation as a spatial HTML comparison artifact (`recommendation.html`) and `ghost-reader recommend` are **not implemented yet**. Recommendation scores, usage analytics, and marketplace ranking live **server-side** (not in local persona YAML) per D003. Until then, users choose personas manually (`mara`, `dex`, `pip`, or optional `elena`, `rook`; or any custom persona validated via `persona show`). Design notes: [skills/ghost-reader/reference.md](skills/ghost-reader/reference.md#phase-3-persona-recommendation-planned).
+
+## Custom personas (skill-mediated, not a CLI command)
+
+There is **no `ghost-reader persona import` or `persona export` command** in any phase. Custom personas are created by the LLM, validated by the CLI:
+
+1. The skill emits canonical YAML matching the persona schema.
+2. Place the file at `$GHOST_READER_HOME/personas/<id>.yaml`.
+3. CLI validates via `ghost-reader persona show <id>` (calls `read_persona()` and the Pydantic schema).
+4. The persona is then usable in `ghost-reader session create --personas <id>,...`.
+
+Local persona YAML may carry `source`, `catalog_ref`, `tags` for provenance. It must NOT carry `matching`, `analytics`, `weights`, `telemetry`, `posture`, or `tolerance` (enforced in `models.py:check_forbidden_fields`). See [skills/ghost-reader/SKILL.md](skills/ghost-reader/SKILL.md#custom-persona-ingestion-llm-driven-not-a-cli-command) and [reference.md](skills/ghost-reader/reference.md#custom-personas-skill-mediated-not-a-cli-command).

ghost_reader-0.0.1/README.md

@@ -0,0 +1,193 @@
+# 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)
+
+**Source:** 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/) if needed, then install the CLI from `main`:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv tool install 'git+ssh://git@github.com/clchinkc/ghost-reader.git'
+ghost-reader help
+ghost-reader update check
+```
+
+Requires access to the private repo (SSH key or `gh auth login` for HTTPS git URLs).
+
+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 |
+
+No hosted web service, no authentication server, no API keys. The `serve` command binds to `127.0.0.1` only — local-first by design.
+
+## Current status (Phase 2)
+
+- 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.
+- 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).
+
+No hosted web app. Phase 3 persona recommendation is **planned** (not in the CLI yet); see roadmap below.
+
+## Install (users)
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) first.
+
+| Method | Command |
+|--------|---------|
+| **pipx** (recommended) | `pipx install ghost-reader` |
+| **uv tool** (recommended) | `uv tool install ghost-reader` |
+| **uvx** (no install) | `uvx ghost-reader help` |
+| **Git (private repo)** | `uv tool install 'git+ssh://git@github.com/clchinkc/ghost-reader.git'` |
+| **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`).
+`pipx install` places it in a pipx-managed virtualenv.
+
+```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 via OIDC trusted publishing on `git tag v*`. The version in `pyproject.toml` is the single source of truth — keep it in sync with `src/ghost_reader/__init__.py` and `src/ghost_reader/.release-version`.
+
+## 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 |
+
+## Roadmap
+
+### Phase 1 — local CLI (shipped)
+Local-first persona-driven review, structured YAML, HTML report, validation gates.
+
+### Phase 2 — iterative rounds (shipped)
+Multi-round workflow, dialogue with personas, bidirectional serve UI, content-safe telemetry, local sync bundle. See [skills/ghost-reader/SKILL.md](skills/ghost-reader/SKILL.md).
+
+### Phase 2.5 — CLI feedback-loop extension (planned, doc-first)
+Extend the existing CLI loop (`serve` → `feedback add/summary` → `prompt revision`) for future remote-catalog sync without breaking local-first operation. Outbound: content-safe events + selected persona IDs + acted-on feedback categories + catalog refs + recommendation receipts. Inbound: catalog metadata + recommendation candidates + receipt IDs. **Raw story text never syncs by default.** No new command surface in this phase — `sync` is extended in docs first, then code.
+
+### Phase 3 — hosted option + remote catalog + recommendation engine (planned)
+Persona recommendation as a spatial HTML comparison artifact (`recommendation.html`) and `ghost-reader recommend` are **not implemented yet**. Recommendation scores, usage analytics, and marketplace ranking live **server-side** (not in local persona YAML) per D003. Until then, users choose personas manually (`mara`, `dex`, `pip`, or optional `elena`, `rook`; or any custom persona validated via `persona show`). Design notes: [skills/ghost-reader/reference.md](skills/ghost-reader/reference.md#phase-3-persona-recommendation-planned).
+
+## Custom personas (skill-mediated, not a CLI command)
+
+There is **no `ghost-reader persona import` or `persona export` command** in any phase. Custom personas are created by the LLM, validated by the CLI:
+
+1. The skill emits canonical YAML matching the persona schema.
+2. Place the file at `$GHOST_READER_HOME/personas/<id>.yaml`.
+3. CLI validates via `ghost-reader persona show <id>` (calls `read_persona()` and the Pydantic schema).
+4. The persona is then usable in `ghost-reader session create --personas <id>,...`.
+
+Local persona YAML may carry `source`, `catalog_ref`, `tags` for provenance. It must NOT carry `matching`, `analytics`, `weights`, `telemetry`, `posture`, or `tolerance` (enforced in `models.py:check_forbidden_fields`). See [skills/ghost-reader/SKILL.md](skills/ghost-reader/SKILL.md#custom-persona-ingestion-llm-driven-not-a-cli-command) and [reference.md](skills/ghost-reader/reference.md#custom-personas-skill-mediated-not-a-cli-command).

ghost_reader-0.0.1/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "ghost-reader"
+version = "0.0.1"
+description = "Persona-driven fiction review simulator CLI"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Kevin Chin", email = "kevin@kevindchin.com"},
+]
+keywords = ["fiction", "beta-reader", "writing", "feedback", "review", "persona"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Text Processing :: General",
+]
+dependencies = [
+    "PyYAML>=6.0.2",
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/clchinkc/ghost-reader"
+Repository = "https://github.com/clchinkc/ghost-reader"
+Documentation = "https://github.com/clchinkc/ghost-reader/blob/main/agent-setup.md"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.4.0",
+]
+
+[project.scripts]
+ghost-reader = "ghost_reader.cli:entrypoint"
+
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ghost_reader = [".release-version", "defaults/personas/*.yaml", "defaults/templates/*.html"]
+
+[tool.ruff]
+src = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "."]
+markers = [
+    "llm: tests that require a live LLM (Gemini) API",
+]

ghost_reader-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ghost_reader-0.0.1/setup.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from pathlib import Path
+import tomllib
+
+from setuptools import setup
+from setuptools.command.build_py import build_py as _build_py
+
+
+class build_py(_build_py):
+    def run(self) -> None:
+        super().run()
+        version = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))[
+            "project"
+        ]["version"]
+        target = Path(self.build_lib) / "ghost_reader" / ".release-version"
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(f"{version}\n", encoding="utf-8")
+
+
+setup(cmdclass={"build_py": build_py})

ghost_reader-0.0.1/src/ghost_reader/.release-version

@@ -0,0 +1 @@
+0.0.1

ghost_reader-0.0.1/src/ghost_reader/__init__.py

@@ -0,0 +1,3 @@
+"""Ghost Reader local-first CLI package."""
+
+__version__ = "0.0.1"

ghost_reader-0.0.1/src/ghost_reader/agent_loader.py

@@ -0,0 +1,64 @@
+"""Load agent YAML definitions for Ghost Reader personas."""
+
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+
+def discover_agent_personas(home: Path) -> list[str]:
+    """Scan agents/ directory for *.agent.yaml files and extract persona IDs."""
+    agents_dir = home / "agents"
+    persona_ids: list[str] = []
+    if agents_dir.exists():
+        for f in sorted(agents_dir.glob("*.agent.yaml")):
+            try:
+                raw = f.read_text(encoding="utf-8")
+                agent = yaml.safe_load(raw)
+                pid = (agent.get("metadata") or {}).get("persona_id")
+                if pid:
+                    persona_ids.append(pid)
+            except (yaml.YAMLError, OSError, AttributeError):
+                continue
+    return persona_ids or _legacy_personas()
+
+
+def _legacy_personas() -> list[str]:
+    """Fallback to hardcoded persona list when no agent YAML files found."""
+    return ["mara", "dex", "pip", "elena", "rook"]
+
+
+def load_agent_yaml(home: Path, persona_id: str) -> Optional[dict]:
+    """Load an agent YAML for a specific persona ID. Returns parsed dict or None."""
+    agents_dir = home / "agents"
+    if not agents_dir.exists():
+        return None
+    for f in sorted(agents_dir.glob("*.agent.yaml")):
+        try:
+            raw = f.read_text(encoding="utf-8")
+            agent = yaml.safe_load(raw)
+            pid = (agent.get("metadata") or {}).get("persona_id")
+            if pid == persona_id:
+                return dict(agent)
+        except (yaml.YAMLError, OSError, AttributeError):
+            continue
+    return None
+
+
+def load_persona_from_agent(home: Path, persona_id: str) -> Optional[dict]:
+    """Load an agent YAML and extract persona-compatible data.
+    
+    Returns a dict with id, source, model, and system_prompt fields,
+    suitable for use by read_persona() and review generation.
+    """
+    agent = load_agent_yaml(home, persona_id)
+    if not agent:
+        return None
+    return {
+        "id": persona_id,
+        "source": "agent_yaml",
+        "model": agent.get("model"),
+        "system_prompt": agent.get("system"),
+        "tools": agent.get("tools", []),
+        "metadata": agent.get("metadata", {}),
+    }