Skip to content

AGENTS.md

Latest commit

 

History

History
230 lines (181 loc) · 11.9 KB

AGENTS.md

File metadata and controls

230 lines (181 loc) · 11.9 KB
Raw

Repository Guidelines

Active Kepano / Shannon Work

Before continuing the current extraction-improvement tranche, read docs/handoffs/KEPANO_SHANNON.md. The crucial starting fact is that Kepano's example is Shannon's A Mathematical Theory of Communication PDF; it is not a separate example to locate.

Project Structure & Module Organization

  • server/index.js: Node MCP server exposing PDF tools shared by Claude Desktop and Cursor. Keep tool definitions and helper utilities here; prefer incremental updates over rewrites.
  • pdf-toolkit-mcp-share/: Packaged variant used by package-for-friend.js; mirror changes from server/index.js when APIs evolve.
  • manifest.json and index.html: Claude Desktop extension metadata and UI stub. Update versions alongside package.json.
  • example-fw9.pdf: Sample form for smoke tests. Keep anonymized assets only.

Tools currently shipped

This is the complete registered set, not a selection.

  • display_pdf, list_pdfs, read_pdf_fields, fill_pdf, bulk_fill_from_csv, save_profile, load_profile, list_profiles, fill_with_profile, extract_to_csv, validate_pdf, read_pdf_content, read_pdf_pages, read_pdf_layout, search_pdf_text, convert_pdf_to_markdown, verify_table_proposal, get_pdf_identity, get_pdf_info, get_page_analysis, inspect_pdf_accessibility, compare_pdfs, render_pdf_page, render_pdf_region, fetch_pdf_from_url, merge_pdfs, split_pdf, rotate_pdf_pages, reorder_pdf_pages, apply_page_plan, create_signature, list_signatures, load_signature, detect_signature_zones, add_signature_field, prepare_signing_packet, apply_signature, apply_text, start_lumin_authorization, finish_lumin_authorization, prepare_lumin_request, send_lumin_request, check_lumin_status, download_lumin_artifact, get_active_document, set_active_document, get_allowed_directories, get_pdf_resource_uri, create_extraction_workspace, inspect_extraction_state, read_extraction_workspace, read_extraction_chunk, submit_extraction_proposal, verify_extraction_proposal, delete_extraction_workspace, reveal_in_finder, read_pdf_bytes (app-only).

get_pdf_info returns bounded source-bound observations. Widget annotations belong to form fields; ordinary annotations remain separate and their targets are returned only as inert values. Render tools bind PNG and, when native canvas is available, raw RGBA digests to the exact source SHA-256. Render-region inputs are top-left PDF.js viewport points after CropBox, rotation, and UserUnit, not MediaBox-relative signing coordinates. The macOS system renderer uses the same view mapping for whole pages and regions and reports raw pixels unavailable.

inspect_pdf_accessibility performs a bounded, local, read-only review of exactly eight shallow catalog-level signals in an unencrypted PDF. It binds observations to the source SHA-256, distinguishes missing from unavailable signals, and always requires human review. It does not establish PDF/UA, WCAG, certification, legal, or document-accessibility conclusions.

compare_pdfs performs a bounded, local, read-only whole-document comparison of two PDFs with at most 20 pages each. It binds observations and evidence to both immutable source envelopes, keeps seven coverage channels separate, preserves ambiguous page matches, and emits reversible default-material or forensic presentation decisions. A successful result is a detected-change set, never a document-equivalence claim.

Build, Test, and Development Commands

  • npm install: install dependencies with Node.js 20.19+ or 22.12+; this is the contributor build/test floor imposed by Vite, not a claim about the Node runtime embedded by a desktop host.
  • node server/index.js: run the MCP server over stdio for local hosts (Cursor, Claude) and watch stderr for diagnostics.
  • node package-for-friend.js: regenerate pdf-toolkit-mcp.zip; requires the zip CLI and ensures shareable installers stay current.
  • npm run build:mcpb: build the UI, create a clean production bundle with the locked macOS/Windows native canvas packages, and verify the .mcpb contents.
  • npm run smoke:mcpb -- pdf-toolkit-mcp.mcpb: start the extracted artifact and require tool discovery plus native page rendering on each release platform.
  • npm test: run the Vitest partition only.
  • npm run test:node-native: run the explicit platform partition of Node native-test suites.
  • npm run test:all: run the unfiltered Vitest and native partitions; use this aggregate gate for release qualification.

Coding Style & Naming Conventions

  • Use 2-space indentation, const/let semantics, and double-quoted strings to match server/index.js and shipped bundles.
  • Favor composable helpers over inlined logic; reuse resolvePath, fillPdfFields, and profile utilities instead of duplicating them.
  • Tool names stay snake_case (list_pdfs, fill_pdf); new tools should follow that pattern and return structured text blocks.

Testing Guidelines

  • Run the narrowest relevant automated tests first, then npm run test:all for release qualification. Automated stdio evidence does not replace manual host runs against example-fw9.pdf; exercise list_pdfs, read_pdf_fields, fill_pdf, and one profile flow.
  • Validate CSV workflows with a two-row fixture before publishing; include a value with a comma to catch CSV parsing regressions.
  • Smoke-test new tools: extract_to_csv on two PDFs, validate_pdf on a partially filled form, read_pdf_content on a text-layer PDF and a textless scanned PDF to verify its page-1 image fallback, and get_pdf_resource_uri with a local file path.
  • Exercise compare_pdfs with the seven deterministic synthetic roles (semantic, text, structure, form, annotation, metadata, and visual), plus an identical/noise control and an inserted-page ambiguity case.

Commit & Pull Request Guidelines

  • Follow the existing imperative subject style (Update index.html to improve structure). Group related changes and note version bumps explicitly.
  • Include PR context: summary of affected tools, manual test evidence, linked issue if applicable, and screenshots only when UI assets change.
  • Regenerate artifacts (pdf-toolkit-mcp.zip, .mcpb) in separate commits or attach them to releases rather than merging binaries directly. Keep version numbers aligned across package.json, manifest.json, and the share bundle.

Maintainer Docs

  • docs/MAINTAINERS.md for architecture, packaging, and manual test checklist.
  • docs/RELEASE.md for release steps and artifact handling.
  • docs/SUPPORT.md for issue intake and triage flow.

Upstream Tracking

Security & Configuration Tips

  • Never hard-code personal paths; rely on resolvePath and default directories (~/Documents, ~/.pdf-toolkit-files).
  • Scrub PDFs or CSVs before committing, and point contributors to local-only credentials files when testing protected documents.

Autonomous Maintainer Run Contract

When the maintainer has authorized an autonomous tranche or epic, do not stop after planning, a single Bead, or a small progress report. Follow docs/ORCHESTRATION.md and continue through ready work until the tranche's exit criteria are met or a genuine human gate is reached.

  • Use Beads as the durable scheduler; claim one bounded task per execution lane.
  • Use Agent Mail for identity, inboxes, handoffs, and file reservations when it is healthy. Use isolated worktrees even when reservations are available.
  • Code-changing parallel lanes use dedicated worktrees under /home/mat/Sites/pdf-tools-worktrees/; do not edit the shared checkout.
  • Commit locally at coherent checkpoints. The control tower batches merges and Git pushes at milestones to limit downstream build-minute costs.
  • Every implementation lane must verify, adversarially review, record evidence, hand off, release reservations, and either take the next ready task or stop at an explicit gate.
  • Progress updates are informational and do not require the maintainer to say “continue.” Ask only when authority, credentials, money, irreversible state, legal/commercial judgment, or a materially ambiguous product choice is needed.
  • Never autonomously publish a release, execute a signature, disclose an unpatched vulnerability, post contractual/legal claims, spend money, or alter production/external data. Those remain human gates.
  • If context is compacted or a session restarts, recover from Git, Beads, docs/ORCHESTRATION.md, Agent Mail, and the evidence ledger rather than relying on chat history.

Issue Tracking with bd (beads)

IMPORTANT: This project uses bd (beads) for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.

Why bd?

  • Dependency-aware: Track blockers and relationships between issues
  • Git-friendly: Dolt-powered version control with native sync
  • Agent-optimized: JSON output, ready work detection, discovered-from links
  • Prevents duplicate tracking systems and confusion

Quick Start

Check for ready work:

bd ready --json

Create new issues:

bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json

Claim and update:

bd update <id> --claim --json
bd update bd-42 --priority 1 --json

Complete work:

bd close bd-42 --reason "Completed" --json

Issue Types

  • bug - Something broken
  • feature - New functionality
  • task - Work item (tests, docs, refactoring)
  • epic - Large feature with subtasks
  • chore - Maintenance (dependencies, tooling)

Priorities

  • 0 - Critical (security, data loss, broken builds)
  • 1 - High (major features, important bugs)
  • 2 - Medium (default, nice-to-have)
  • 3 - Low (polish, optimization)
  • 4 - Backlog (future ideas)

Workflow for AI Agents

  1. Check ready work: bd ready shows unblocked issues
  2. Claim your task atomically: bd update <id> --claim
  3. Work on it: Implement, test, document
  4. Discover new work? Create linked issue:
    • bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>
  5. Complete: bd close <id> --reason "Done"

Auto-Sync

bd automatically syncs via Dolt:

  • Each write auto-commits to Dolt history
  • Use bd dolt push/bd dolt pull for remote sync
  • No manual export/import needed!

Important Rules

  • ✅ Use bd for ALL task tracking
  • ✅ Always use --json flag for programmatic use
  • ✅ Link discovered work with discovered-from dependencies
  • ✅ Check bd ready before asking "what should I work on?"
  • ❌ Do NOT create markdown TODO lists
  • ❌ Do NOT use external issue trackers
  • ❌ Do NOT duplicate tracking systems

For more details, see README.md and docs/QUICKSTART.md.

Landing the Plane (Session Completion)

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

  1. File issues for remaining work - Create issues for anything that needs follow-up
  2. Run quality gates (if code changed) - Tests, linters, builds
  3. Update issue status - Close finished work, update in-progress items
  4. PUSH TO REMOTE - This is MANDATORY: 
    git pull --rebase
bd dolt push
git push
git status  # MUST show "up to date with origin"
  5. Clean up - Clear stashes, prune remote branches
  6. Verify - All changes committed AND pushed
  7. Hand off - Provide context for next session

CRITICAL RULES:

  • Work is NOT complete until git push succeeds
  • NEVER stop before pushing - that leaves work stranded locally
  • NEVER say "ready to push when you are" - YOU must push
  • If push fails, resolve and retry until it succeeds