storyai

Open this first → docs/index.html

Opening it in a browser links the seven documents to one another. To view everything in a single page, use docs/storyai-설계-통합.html. If you're curious about the screens, docs/07-UI목업.html — it actually works.

Related MCP server: bible-ecrivain

What's in this folder

docs/     읽을 것.  설계 문서 7종 + 통합본
spec/     구현이 읽을 것.  온톨로지·툴·규칙·DDL (JSON + SQL)
build/    문서를 고칠 때.  parts/ 수정 후 build.py 실행
skills/   에이전트가 읽을 것.  집필·검수·설정집 3종
hooks/    자동 검사 트리거.  Claude Code / Codex 각각
AGENTS.md 에이전트 지침 단일 소스 ★ 양쪽 호스트가 읽음

manuscript/ api/ web/        ← 후속 단계에서 채웁니다
server/ bible/ store/        ← P0 조회 + P1 제안/커밋 구현

Documents

Open docs/index.html in a browser. The seven documents reference one another.

Machine-readable spec

The files that the documents describe and that the implementation reads directly.

spec/ontology.json   노드 18종 · 간선 28종 · 태그 · 삼중 시간축 · 가시성 · 불변식
spec/tools.json      MCP 툴 15개 시그니처 · 예산 · 위험 등급 정책
spec/rules.json      진단 규칙 26개 (Tier 1 결정론 / Tier 2 LLM) · 전파 정책
spec/policy.json     P1 변경 위험 등급 · 잠금 · 캐스케이드 임계값
spec/schema.sql      DDL — 테이블 22 · 뷰 5 · 인덱스 18

Applied immediately with sqlite3 store/story.db < spec/schema.sql.

Host packages

Works as a single set on both Claude Code and Codex.

plugin.json                 agent-plugins 스키마 — Codex가 우선 인식
.claude-plugin/plugin.json  Claude Code 매니페스트 — Codex도 폴백으로 읽음
.mcp.json                   Claude Code용 프로젝트 MCP 설정
.codex/config.toml          Codex용 프로젝트 MCP 설정
AGENTS.md                   ★ 에이전트 지침 단일 소스. 양쪽이 읽음
CLAUDE.md                   AGENTS.md를 가리키는 한 줄
skills/                     Agent Skills 규격 6필드만 — 양쪽 + 46개 호스트
hooks/                      run-check.sh 를 양쪽 훅이 공통 호출

MCP connection check

The repository contains both .mcp.json for Claude Code and .codex/config.toml for Codex. When you first open it, trust the project, approve MCP execution, and then verify the connection status.

claude mcp list
codex mcp list

Editing the documents

The documents are build artifacts. To change the content, edit build/parts/*.part.html and:

python3 build/build.py

The shared style lives in a single place, build/style.css, and is inlined into each document at build time — which is why each document is self-contained and renders as-is wherever you host it. The only dependency is the Python standard library.

Implementation status

P0 read-only index, P1 write path, P2 dual-line·diagnostics, and P3 extraction·search are implemented. It provides 14 MCP tools, and every write goes through proposal logging and read_set conflict adjudication before being applied atomically in a single SQLite commit lane. P3 enforces an explicit ID binding manifest and UTF-8 byte spans, and combines BM25 with local sqlite-vec results via RRF.

Next up is P4 — UI. For the detailed breakdown, follow 개발계획서 §P4.

Development run

Create an isolated environment on Python 3.12 or later and install development dependencies.

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

The config file format follows bible/README.md. The loader reads only the explicitly specified YAML metadata and does not guess or auto-extract content.

.venv/bin/python -m server.load_bible
.venv/bin/python -m server.consolidate
.venv/bin/python -m pytest
server/run-mcp.sh

Manuscript extraction uses *.story.json files next to manuscript/**/*.md as input. The format and LLM extraction contract live in prompts/v1/, and ingest only creates Proposals — it does not auto-commit.

The last command is a stdio MCP server, so it waiting in the terminal is normal. Claude Code and Codex both run the same server/run-mcp.sh entrypoint through their respective project settings.

P1 write contract

propose does not mutate the live graph. Each op requires a unique idem_key of 8+ characters, and read_set cannot be empty. For an ADD with no basis in existing nodes — like the initial Session — the current graph_state.revision is passed as { "node": "book", "rev": n }.

Supported verbs are ADD · UPDATE · INVALIDATE · LINK · UNLINK. INVALIDATE and UNLINK do not delete rows; they close tx_to. commit(mode="dry_run") performs the same validation, CID, and Merkle calculations as the real thing, then rolls back the entire transaction.

story://session/latest points to the most recent Session node. The Session's props must retain open_threads and next so the next host can pick up where it left off.

P2 dual-line·continuity contract

A Promise's props.status only advances in the order hypothetical → eligible → actualized, and an intentional discard ends in prevented. eligible requires T, and actualized requires P. promises(status=["eligible"]) returns F–T–P, debts, S-Eff, and delta-Coh approximations.

Fact visibility records viewer, learned_at, and pathway in visible_to. A Scene's props.pre · post · forbid conditions take the form subject, field, op, value, and utterance facts are recorded as props.claims=[{"speaker": "character/…", "fact": "fact/…"}]. Using this structure lets check adjudicate perception timing, world rules, and fact conflicts reproducibly in SQL.

Cycles in causes, contains, and extends, plus a second focalizes edge per Scene, are rejected at the proposal stage. The remaining diagnostics, including unreachable events, are verified in the commit result and via check.