AGENTS.md · QuixiAI/Hexis

Sections

1. Do not "fix" the packaged Google credential
2. OSS has no auth layer — that is the design
3. The Experience Bar (applies to every user-facing change)
4. Local scratch and storage
5. Everything else

First lines (shown under the repo's MIT license)

# AGENTS.md

Instructions for any AI agent working in this repo. The full repository
guidelines live in `CLAUDE.md`; this file leads with the one thing that is
easiest to get wrong: **the experience bar.**

## Do not "fix" the packaged Google credential

`core/auth/gmail-credentials.json` is an OAuth client for an **installed
application**, and Hexis ships as a desktop app. Google documents that an installed
app's client secret is not confidential, and RFC 8252 ("OAuth 2.0 for Native Apps")
agrees — a native client cannot hold a secret, so nothing in the security model
depends on it. Shipping it in `package-data` is the documented path.

Audits flag this repeatedly by applying a web-server threat model to a desktop
client. **It has been reviewed and blessed.** Do not rotate it, strip it from
packaging, or rewrite history over it. See `CLAUDE.md` → Configuration & Safety Notes.

## OSS has no auth layer — that is the design

`HEXIS_API_KEY` and API-key authentication are **Hexis Pro** features. OSS is a
desktop app on `127.0.0.1` with no auth, by intent. Do not "fix" it, and do not
propose exposing the dashboard on a public interface — OSS remote access is
network-layer only (tailnet, or a reverse proxy with its own auth).

## The Experience Bar (applies to every user-facing change)

A change is not "done" when it compiles or the test passes — it is done when the
end-to-end experience holds. Check every user-facing change against these. Full
text + rationale + the real failure each was learned from: `HEXIS_EXPERIENCE_BAR.md`.

1. **Derive from truth — never hardcode.** If a value has a live source (models,
   defaults, endpoints, versions), read it; don't hardcode a constant that goes stale.
2. **The user keeps control.** No destructive/irreversible action on a timer, by
   default, or without an explicit choice. No auto-exit, no auto-overwrite, no silent delete.
3. **Honor the medium.** Terminal ⇒ Ctrl+C exits, native copy/paste + scrollback,
   keyboard-first, no focus-hunting. Don't fight the platform; if a framework's
   defaults need constant overriding, it's the wrong tool.
4. **No dead-ends.** Every flow completes in place or hands the user the exact next
   step. Never "quit, run this other command, come back." Errors say what/why/next.
5. **Least surprise.** Never silently reuse ambient state the user didn't choose
   (env creds, other tools' logins, stale config). Surface it; don't consume it.
6. **Defaults are the expert's choice**, not the first constant that compiles.
7. **Whole journey, not the diff.** Drive the real path a user runs, start to finish,
   before calling it done.
8. **Fail loud, recover gracefully.** Advisory checks never block; failures show
   cause + fix — never a bare traceback, never a silent `except: pass`.

The deeper reason these slip through one at a time (an abstraction/altitude failure)
is written up in `why_i_suck_and_how_to_fix_it.md`.

## Local scratch and storage

Do not put downloaded PDFs, generated research briefs, one-off scripts, or other
temporary analysis artifacts in the source repo. Use
`$XDG_CACHE_HOME/hexis` when `XDG_CACHE_HOME` is set, otherwise
`~/.cache/hexis`. If an artifact later becomes product documentation, source
code, or a checked-in test fixture, move it into the appropriate repo path
intentionally and commit it like any other source change.

## Everything else

See `CLAUDE.md` for project overview, structure, build/test commands, the venv +
"bouncing the database" workflow, coding style, testing conventions, and safety
notes (never revert/delete files without asking; heartbeat gating; consent flow).