calibre-catalog-read

name: calibre-catalog-read description: "Read-only Calibre catalog lookup, ID viewing, and one-book analysis comments workflow over a running Content server. Use for list/search/id viewing, including ID requests without edit verbs. Never for title/authors/tags/series/series_index metadata edits." metadata: {"openclaw":{"requires":{"bins":["node","uv","calibredb","ebook-convert"],"env":["CALIBRE_PASSWORD"]},"optionalEnv":["CALIBRE_USERNAME"],"primaryEnv":"CALIBRE_PASSWORD","dependsOnSkills":["subagent-spawn-command-builder"],"localWrites":["skills/calibre-catalog-read/state/runs.json","skills/calibre-catalog-read/state/calibre_analysis.sqlite","skills/calibre-catalog-read/state/cache/**"],"modifiesRemoteData":["calibre:comments-metadata"]}}

Use for Calibre read-only catalog work and the one-book analysis/comments workflow.

Routing

Use this skill for:

list/search/id catalog lookup.
ID viewing: ID 1021 を確認して, 1021番の詳細, show/view/check book 1021.
Natural book conversation where a lightweight library lookup helps.
One-book analysis only when the user clearly asks to read/analyze a book.

Do not use for metadata edits. If the user asks to change title/authors/series/series_index/tags/publisher/pubdate/languages, route to calibre-metadata-apply.

ID alone is not edit intent. 確認/見せて/教えて/詳細/check/show/view means read-only. calibre-metadata-apply requires explicit edit verbs such as 修正/編集/変更/直す/fix/edit/update/change.

Local Facts

Read TOOLS.md for Content server URL, library id, auth policy, and reading script.

Connection bootstrap:

Do not ask the user for --with-library first.
First try scripts without explicit --with-library; they auto-load .env and saved defaults.
Ask for URL only if resolution fails (missing --with-library or unable to resolve usable library).
Non-SSL auth is Digest; do not pass auth-mode/auth-scheme flags.
Never start calibre-server from chat.
Do not assume localhost/127.0.0.1; TOOLS.md has the reachable server.

Requirements: calibredb, ebook-convert, node, uv, and subagent-spawn-command-builder.

Commands

Prefer wrapper scripts over direct calibredb in agent/chat.

List: node skills/calibre-catalog-read/scripts/calibredb_read.mjs list --password-env CALIBRE_PASSWORD --limit 50

Search: node skills/calibre-catalog-read/scripts/calibredb_read.mjs search --password-env CALIBRE_PASSWORD --query 'series:"中公文庫"'

Get by id: node skills/calibre-catalog-read/scripts/calibredb_read.mjs id --password-env CALIBRE_PASSWORD --book-id 3

One-book pipeline with prepared analysis JSON: uv run python skills/calibre-catalog-read/scripts/run_analysis_pipeline.py --password-env CALIBRE_PASSWORD --book-id 3 --lang ja --analysis-json /tmp/calibre_3/analysis.json

Prepare subagent input: node skills/calibre-catalog-read/scripts/prepare_subagent_input.mjs --book-id 3 --lang ja --out-dir /tmp/calibre_3

Run state: node skills/calibre-catalog-read/scripts/run_state.mjs upsert --run-id --book-id 3 --title "..." --state running node skills/calibre-catalog-read/scripts/handle_completion.mjs --run-id --analysis-json /tmp/analysis.json

One-Book Analysis Flow

Use subagent only for heavy reading. Keep main chat as control plane.

Before first subagent run in a session, confirm once:

model
thinking: low|medium|high
runTimeoutSeconds

Reuse confirmed settings for later books in the same session unless the user changes them.

Turn A, start only:

Confirm target book_id.
Prepare input with scripts/prepare_subagent_input.mjs.
Use subagent-spawn-command-builder with profile calibre-read.
Call sessions_spawn.
Save run state with scripts/run_state.mjs upsert.
Reply that analysis is running and stop the turn.

Turn B, completion only:

On completion event, run scripts/handle_completion.mjs with --run-id and --analysis-json.
It applies comments, updates DB, and removes completed run state.
If state is missing, treat as stale/duplicate and do not apply blindly.

Hard rules:

Never poll/wait/apply in Turn A.
Never keep a chat listener turn open waiting for subagent completion.
One book per run.
Main session owns user-facing replies and Calibre comments apply.
Subagent only reads source payload and emits analysis JSON; it must not apply metadata or message the user.
Use strict prompt references/subagent-analysis.prompt.md; do not send ad-hoc relaxed read instructions.
Input schema: references/subagent-input.schema.json; output schema: references/subagent-analysis.schema.json.
Exclude manga/comic-centric books from this text pipeline.
If extracted text is too short, stop and ask for confirmation.
Keep state/runs.json to active/failed records only.
At completion, missing runId means stale/duplicate; do not apply blindly.

Cache And Language

Cache DB is skills/calibre-catalog-read/state/calibre_analysis.sqlite. Treat cache as acceleration, not authority; final user-visible answer should reflect current target and completed run.

Language policy:

Do not hardcode user-language prose in pipeline scripts.
Generate user-visible analysis from subagent output, with language controlled by user-selected settings and lang input.
Fallback local analysis is generic/minimal; preferred path is subagent output following the prompt template.

Detailed legacy notes and command variants: references/full-pre-prune-2026-05-27.md.