calibre-metadata-apply

A skill for updating metadata of existing Calibre books.

Skill selection contract (strict)

• - If the user intent is metadata edit/fix/update, this skill is mandatory.
• If the request mentions an ID together with edit/fix/update intent (e.g. ID1011 タイトル修正, ID1011 のタイトルを直して), this skill is mandatory.
• If the request mentions an ID but only for viewing/checking/confirming (e.g. ID1021 を確認して, ID1021 の詳細), do NOT use this skill — route to calibre-catalog-read.
• INLINECODE5 must not be used for those edit intents.

Use this skill when the user asks any of:

• - "ID指定でタイトル修正"
• "メタデータ編集"
• INLINECODE6 updates

Do NOT use this skill for:

• - Read-only lookups (e.g. "ID 1021 を確認して", "ID 1021 の情報を見せて", "show me book 1021")
• Checking what metadata a book currently has without intent to change it
• Those must use INLINECODE7

Requirements

• - calibredb must be available on PATH in the runtime environment
• INLINECODE9 installed (for spawn payload generation)
• INLINECODE10 is optional/recommended for PDF evidence checks
• Reachable Calibre Content server URL

- http://HOST:PORT/#LIBRARY_ID - If LIBRARY_ID is unknown, use #- once to list available IDs on the server.

• - --with-library can be omitted only when one of these is configured:

- env: CALIBRE_WITH_LIBRARY or CALIBRE_LIBRARY_URL or CALIBRE_CONTENT_SERVER_URL - optional library id completion: CALIBRE_LIBRARY_ID

• - Read the "Calibre Content Server" section of TOOLS.md for the correct --with-library URL.
• Host failover (IP change resilience):

- Optional env: CALIBRE_SERVER_HOSTS=host1,host2,... - Script auto-tries candidates, including WSL host-side nameserver from /etc/resolv.conf.

• - If authentication is enabled, prefer /home/altair/.openclaw/.env:

- CALIBRE_USERNAME=<user> - CALIBRE_PASSWORD=<password>

• - Auth scheme policy for this workflow:

- Non-SSL deployment assumes Digest authentication. - Do not pass auth mode arguments such as --auth-mode / --auth-scheme.

• - Pass --password-env CALIBRE_PASSWORD (username auto-loads from env)
• You can still override explicitly with --username <user>.

Supported fields

Direct fields (set_metadata --field)

• - INLINECODE31
• INLINECODE32
• INLINECODE33 (string with & or array)
• INLINECODE35
• INLINECODE36
• INLINECODE37
• INLINECODE38 (string or array)
• INLINECODE39
• INLINECODE40 (YYYY-MM-DD)
• INLINECODE42
• INLINECODE43

Helper fields

• - comments_html (OC marker block upsert)
• INLINECODE45 (auto-generates analysis HTML for comments)
• INLINECODE46 (adds tags)
• INLINECODE47 (default true)
• INLINECODE49 (remove specific tags after merge)

Required execution flow

A. Target confirmation (mandatory)

1. 1. Run read-only lookup to narrow candidates
2. Show INLINECODE50
3. Get user confirmation for final target IDs
4. Build JSONL using only confirmed IDs

B. Proposal synthesis (when metadata is missing)

1. 1. Collect evidence from file extraction + web sources
2. Show one merged proposal table with:

- candidate, source, confidence (high|medium|low) - title_sort_candidate, author_sort_candidate

1. 3. Get user decision:

- approve all - approve only: <fields> - reject: <fields> - edit: <field>=<value>

1. 4. Apply only approved/finalized fields
2. If confidence is low or sources conflict, keep fields empty

C. Apply

1. 1. Run dry-run first (mandatory)
2. Run --apply only after explicit user approval
3. Re-read and report final values

Analysis worker policy

• - Use subagent-spawn-command-builder to generate sessions_spawn payload for heavy candidate generation

- task is required. - Profile should include model/thinking/timeout/cleanup for this workflow.

• - Use lightweight subagent model for analysis (avoid main heavy model)
• Keep final decisions + dry-run/apply in main

Data flow disclosure

• - Local execution:

- Build calibredb set_metadata commands from JSONL. - Read/write local state files (state/runs.json).

• - Subagent execution (optional for heavy candidate generation):

- Uses sessions_spawn via subagent-spawn-command-builder. - Text/metadata sent to subagent can reach model endpoints configured by runtime profile.

• - Remote write:

- calibredb set_metadata updates metadata on the target Calibre Content server.

Security rules:

• - Prefer env-based password (--password-env CALIBRE_PASSWORD) over inline --password.
• If user does not want external model/subagent processing, keep flow local and skip subagent orchestration.
• In agent/chat execution, do not call calibredb directly for edit operations.

- Always execute node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs.

• - Never run calibre-server from this skill.

- This workflow always targets an already-running Calibre Content server.

Connection bootstrap (mandatory)

• - Do not ask the user for --with-library first.
• First, execute using saved defaults (env) with no explicit --with-library.

- Scripts auto-load .env and resolve CALIBRE_WITH_LIBRARY / CALIBRE_CONTENT_SERVER_URL.

• - Ask user for URL only when command output shows unresolved connection, such as:

- missing --with-library - unable to resolve usable --with-library - repeated connection failures for all candidates

Long-run turn-split policy (library-wide)

For library-wide heavy processing, always use turn-split execution.

Unknown-document recovery flow (M3)

Batch sizing rule:

• - Keep each unknown-document batch small enough to show full row-by-row results in chat (no representative sampling).
• If unresolved items remain, stop and wait for explicit user instruction to start the next batch.

User intervention checkpoints (fixed)

1. 1. Light pass (metadata-only)

- Always run this stage by default (no extra user instruction required) - Analyze existing metadata only (no file content read) - Present a table to user: - current file/title - recommended title/metadata - confidence/evidence summary - Stop and wait for user instruction before any deeper stage

1. 2. On user request: page-1 pass

- Read only the first page and refine proposals - Report delta from light pass

1. 3. If still uncertain: deep pass

- Read first 5 pages + last 5 pages - Add web evidence search - Produce finalized proposal with confidence + rationale

1. 4. Approval gate

- Show detailed findings and request explicit approval before apply

Pending and unsupported handling

• - Use pending-review tag for unresolved/hold items.
• If document is unresolved in current flow, do not force metadata guesses.

- Tag with pending-review and keep for follow-up investigation.

Diff report format (for unknown batch runs)

Return full results (not samples):

• - execution summary (target/changed/pending/skipped/error)
• full changed list with id + key before/after fields
• full pending list with id + reason
• full error list with id + error summary
• confidence must be expressed as INLINECODE86

Runtime artifact policy

• - Keep run-state and temporary artifacts only while a run is active.
• On successful completion, remove per-run state/artifacts.
• On failure, keep minimal artifacts only for retry/debug, then clean up after resolution.

Internal orchestration (recommended)

• - Use lightweight subagent for all analysis stages
• Keep apply decisions in main session
• Persist run state for each stage in INLINECODE87

Turn 1 (start)

1. 1. Main defines scope
2. Main generates spawn payload via subagent-spawn-command-builder (profile example: calibre-meta), then calls INLINECODE90
3. Save run_id/session_key/task via INLINECODE92
4. Immediately tell the user this is a subagent job and state the execution model used for analysis
5. Reply with "analysis started" and keep normal chat responsive

Turn 2 (completion)

1. 1. Receive subagent completion notice
2. Save result JSON
3. Complete state handling via INLINECODE93
4. Return summarized proposal (apply only when needed)

Run state file:

• - INLINECODE94

PDF extraction policy

1. 1. Try ebook-convert first
2. If empty/failed, fallback to INLINECODE96
3. If both fail, switch to web-evidence-first mode

Sort reading policy

• - Use user-configured reading_script for Japanese/non-Latin sort fields

- katakana / hiragana / latin

• - Ask once on first use, then reuse for the session
• Default policy is full reading (no truncation)
• Read the "Calibre Content Server" section of TOOLS.md for the configured reading_script value; pass it as a CLI argument when needed.

Usage

Dry-run:

CODEBLOCK0

Dry-run (when default library is preconfigured via env/config):

CODEBLOCK1

Apply:

CODEBLOCK2

Do not

• - Do not run direct --apply using ambiguous title matches only
• Do not include unconfirmed IDs in apply payload
• Do not auto-fill low-confidence candidates without explicit confirmation
• Do not start a local server with guessed path like INLINECODE103