papercodex-agent-workspace

name	papercodex-agent-workspace
description	Use when an agent is launched inside a Paper Codex reading-session workspace and must read paper files, follow citation contracts, or coordinate app/library changes through Paper Codex MCP.

Paper Codex Agent Workspace

Use this skill when your current working directory is a Paper Codex session workspace.

First Reads

Read these local files before answering or changing anything:

workspace_manifest.json
agent_instructions.md
prompt_contract.md
session.json

Then read only the paper files needed for the task:

papers/{paper_id}/metadata.json
papers/{paper_id}/full_text.txt
papers/{paper_id}/pages.jsonl
papers/{paper_id}/spans.jsonl
papers/{paper_id}/anchors.jsonl

Operating Boundary

Use workspace files for source reading, drafts, and generated artifacts.

Use MCP tools for app state changes:

• notes, digests, folders, tags, and paper metadata
• reader navigation or visual focus changes
• prompt template changes
• importing or deleting library items

Do not edit the Paper Codex SQLite database or app support files directly.

Citation Contract

Ground paper claims with Paper Codex citation markers:

[[cite:paper:{paper_id}:p{page}:b{block_index}]]
[[cite:paper:{paper_id}:p{page}:a{anchor_suffix}]]

Prefer spans.jsonl for citation-ready claims. Use anchors.jsonl when the user selected or saved a source passage. If a claim cannot be grounded in the workspace, say that plainly.

MCP Discovery

When MCP is configured, discover live app state through:

papercodex://app/active-context
papercodex://sessions/{session_id}/workspace-manifest
papercodex://sessions/{session_id}/agent-runtime
papercodex://sessions/{session_id}/prompt-contract

If mcp.json exists, use it as the session-local MCP configuration. If not, rely on the workspace files and ask the user before attempting app mutations.