agentsview

# Agent Instructions

## Scope

- These rules apply to all agent work in this repository.
- Requests to review, analyze, or explain are read-only unless the user also
  asks for changes.
- Read every focused guide whose route matches the task before editing files.
- More specific instructions override broader ones.
- Keep `CLAUDE.md` as a symlink to this file. Record new durable rules here or
  in the matching focused guide.

## Task Routes

| Task or path                                                                            | Read before editing                  |
| --------------------------------------------------------------------------------------- | ------------------------------------ |
| Features, bug fixes, tests, or test helpers                                             | `docs/agents/testing.md`             |
| SQLite, PostgreSQL, CockroachDB, DuckDB, ClickHouse, archive resync, or storage queries | `docs/agents/storage.md`             |
| Watchers, polling, sync scheduling, background work, or memory investigations           | `docs/agents/background-work.md`     |
| Build commands, toolchains, CI build tags, or dependencies                              | `docs/agents/build.md`               |
| S3 ingest, `S3Provider`, or `Source.S3Discovery`                                        | `docs/agents/s3-providers.md`        |
| Any frontend file                                                                       | `frontend/AGENTS.md`                 |
| Frontend controls, styling, or reusable components                                      | `frontend/AGENTS.md` and `DESIGN.md` |

The `README.md` and `Makefile` are the sources for project facts, setup, and
commands. Do not copy their catalogues into this file.

Before reviewing CI runner security, read the
[Namespace runner policy](docs/agents/build.md#namespace-runner-policy).

## Roborev

- Never run `roborev review` unless the user asks for it.
- Never invoke a roborev skill, including `roborev-fix` or
  `roborev-design-review-branch`, unless the user asks for that skill.
- Other roborev commands may be used when they fit the task.

## Git and Delivery

1. Check the branch state before editing. Do not create or switch branches
   without the user's permission. A Codex-managed detached worktree may
   receive commits; leave branch creation to the user or app.
1. Commit every turn that changes tracked files. Do not make empty commits. If a
   turn is read-only or changes only ignored files, say that no commit was
   made.
1. Keep commits focused and use clear conventional commit messages.
1. Do not amend, squash, rebase, push, or pull unless the user asks.
1. Do not add generated-with lines, attribution blocks, validation footers, or
   command transcripts to commit messages.
1. Deliver changes through pull requests from feature branches. Never merge a
   pull request; merging is the user's decision.

## Safety

- Do not revert user work or unrelated local changes unless the user asks.
- Avoid destructive git commands unless the user asks.
- Never install over a live binary, run migrations against production, or write
  to live data directories without permission. Use isolated scratch data for
  branch builds and profiling.
- For login or OAuth, give the user the exact command instead of driving the
  interactive flow.
- SQLite is the persistent archive. Never delete, drop, truncate, or recreate it
  to handle data-version changes. Read `docs/agents/storage.md` before any
  archive, database, parser-resync, or storage change.

## Content and Publishing

- Keep private project names, hostnames, personal identities, infrastructure
  details, and absolute user paths out of code, tests, fixtures,
  documentation, commit messages, and pull request text. Run the private-data
  scrub before publishing.
- Write changelog entries in plain language for people who do not live in the
  codebase. Lead each entry with the outcome a user or operator will notice.
  Put implementation details after that outcome, and include them only when
  they help the reader act or understand a limit.
- Keep pull request titles and descriptions in sync with the current diff.
- Do not post pull request or issue comments unless the user asks.

## Documentation

- Write for the person trying to use or maintain AgentsView. Lead with the
  outcome, name who does what, use short sentences, and explain unfamiliar
  terms.
- Organize around reader questions. Put purpose and current capabilities first;
  separate limitations and future work. Use only the sections the topic needs.
- Give each bullet one main idea. Use numbered steps for sequences, paragraphs
  for rationale, and tables or diagrams when they clarify a comparison or
  flow.
- State rules directly. Preserve exact commands, field names, authorization
  checks, limits, and failure behavior when simplifying the wording.
- Give each fact an owning guide or reference and link to it elsewhere. Update
  that section instead of appending a narrative of the latest change. Indexes
  should route readers, not repeat implementation status.
- Describe current architecture separately from approved but unbuilt work,
  proposals, and historical decisions. Preserve rationale, approvals, and
  active exceptions with their removal conditions. Label superseded designs
  and keep them outside normal navigation.
- Keep the website, its Markdown companions, README, and documentation on
  message. Distinguish the latest release from newer `main` functionality.
  Follow [docs/README.md](docs/README.md) for the publishing layout and
  checks.
- Verify release notes against the release tags and source. Credit contributors
  from merged pull requests or commit history; do not infer contributions from
  names or issue participation alone.
- Regenerate the full screenshot set for every release and store it on the
  `docs-generated-assets` orphan branch. Add captures for new visible
  features, inspect the images, and preview the assembled website locally
  before opening the release documentation pull request. Follow
  `docs/screenshots/README.md`.

## Definition of Done

- Follow every focused guide matched by the task routes above.
- Run relevant checks before committing when practical. If a check cannot run,
  state that in the handoff.
- After changing Go code, run `go fmt ./...` and `go vet ./...` before
  committing.
- Preserve observable behavior and update documentation when behavior changes.

## Provider Format Provenance

When adding a provider, changing its format or usage/cost accounting, or
investigating a provider release, new artifact generation, parser bug, or usage
discrepancy, consult `docs/internal/session-format-sources.md` and reverify or
update its evidence entry in the same change. Grok remains temporarily excluded
only until its separately owned format-alignment work lands.

## Project Map

agentsview syncs local AI agent sessions into SQLite, serves a Svelte 5 web UI,
and can mirror data to PostgreSQL, DuckDB, or ClickHouse.

- `cmd/agentsview/`: CLI and server entry points
- `internal/db/`: SQLite archive and search
- `internal/postgres/`: PostgreSQL sync and read store
- `internal/duckdb/`: disposable DuckDB mirror and Quack reads
- `internal/clickhouse/`: ClickHouse remote mirror and read store
- `internal/parser/`: agent session parsers
- `internal/server/`: HTTP API and SSE
- `internal/sync/`: discovery, file watching, and sync
- `internal/vector/`: semantic and hybrid search
- `frontend/`: Svelte 5 application

## Conventions

- Prefer the standard library over new dependencies.
- Use `internal/stringutil.SafeTruncate` for byte-limited display text. Add
  truncation markers at the call site and reserve their bytes when the limit
  includes them. Use `internal/stringutil.TruncateRunes` for rune-count
  limits; its limit excludes the supplied suffix. Keep rune-count limits
  distinct from byte limits. Both helpers assume valid UTF-8 and do not
  sanitize malformed input.
- Do not use emojis in code or output.
- Format Markdown with `mdformat --wrap 80` when `mdformat` and
  `mdformat-tables` are available.

## Pull Requests

- Do not poll or watch GitHub Actions checks unless the developer explicitly
  requests it.
- Do not use `gh api` to watch CI jobs unless the user explicitly requests it.
- Write summary-only pull request descriptions. Do not add test plans,
  checklists, command transcripts, or sections named Tests, Testing,
  Verification, or Test plan.
- Explain what the code does now, why it changed, tradeoffs, limits, and where
  reviewers should look.