xurl AGENTS.md

Agent Guidelines

Workspace Responsibilities

• xurl-core: all URI parsing, provider resolution, raw file reading, and markdown rendering lives here. It owns provider-specific parsers for Codex, Claude, and OpenCode plus the shared service layer (resolve_thread, render_thread_markdown, render_thread_head_markdown).
• xurl-cli: thin CLI that parses xurl <uri> arguments with clap, wires up ProviderRoots::from_env_or_home, emits metadata warnings to stderr, and prints rendered markdown (render_thread_markdown).

CLI Parameter & Provider Behavior Matrix

• The CLI accepts a single <uri> and an optional -I/--head flag for frontmatter-only output.
• ProviderRoots::from_env_or_home sources the base directories using:
  • Codex: CODEX_HOME then ~/.codex
  • Claude: CLAUDE_CONFIG_DIR then ~/.claude
  • OpenCode: XDG_DATA_HOME/opencode then ~/.local/share/opencode
• render_thread_markdown converts provider payloads into a markdown thread view with frontmatter metadata plus user/assistant-focused content; warnings from resolved.metadata.warnings are emitted to stderr before the primary output.

Design Docs

• Design documents live under docs/.
• Before proposing, implementing, or revising URI behavior, query behavior, or other user-facing semantics, read the relevant design docs in docs/ first and align with them.
• If implementation diverges from an existing design doc, update the design doc in the same change or explain clearly why the divergence is intentional.

Error Handling & Exit Contract

• main maps any xurl_core::Result failure to a non-zero exit code (1) and prints error: <message> on stderr; successes return exit code 0.
• Common failure cases include invalid URI syntax, missing provider roots, unresolved session IDs, unreadable files, empty files, and non-UTF-8 payloads (read_thread_raw explicitly guards against empty and non-UTF8 data).
• Metadata warnings and diagnostics are printed on stderr but do not change the exit code, making it clear that only Err results trigger failure.