Imported from stainedhead/ingatan-webui (AGENTS.md). Install upstream with npx skills add stainedhead/ingatan-webui. Copyright stays with the author.

AGENTS.md

Rules and guidelines for AI agents working on ingatan-webui — the standalone browser-based interface for the ingatan second brain service. A Go binary that serves server-rendered HTML via templ + HTMX, calling the ingatan REST API as its backend. No business logic — the WebUI is a rendering layer over the ingatan REST API.

Architecture

ingatan-webui is a standalone HTTP server — NOT embedded in the ingatan binary. It has no domain or usecase layers. All data operations go through the ingatan REST API.

cmd/ingatan-webui/main.go    # Entry point + router setup
internal/
  handler/                   # HTTP handlers: full-page routes (GET /*) and HTMX fragments (GET|POST /ui/*)
  client/                    # ingatan REST API client (same pattern as ingat CLI client)
  session/                   # HttpOnly cookie session management, JWT storage, CSRF tokens
  config/                    # Config loader: ~/.ingatan-webui/config.yaml + env vars
  webui/
    templates/
      layout/                # base.templ, nav.templ
      pages/                 # Full-page templ templates (search, memory, stores, conversations, health, login)
      fragments/             # HTMX partial templ templates (search_results, memory_card, etc.)
    static/                  # Pre-built TailwindCSS, vendored HTMX + Alpine.js (go:embed)

Design Mandate:

• Standalone deployment — separate binary and process from ingatan server.
• No business logic — call the ingatan REST API, render the result as HTML. No data stored locally.
• No Node.js at runtime — templ compiled to Go at build time; TailwindCSS pre-built offline.
• All assets embedded via go:embed — no files required on disk at runtime.
• HTMX drives all dynamic updates — server returns HTML fragments, not JSON.
• Authentication via HttpOnly session cookies — JWT stored server-side, never exposed to browser JS.

TDD: Red → Green → Refactor

All three phases are mandatory. Refactor is not optional.

1. Red: Write a failing test. Verify it fails for the right reason.
2. Green: Minimal code to pass. No premature optimization.
3. Refactor: Eliminate duplication, improve naming, extract functions, simplify logic. Run tests after each change.

Tests in <file>_test.go (same package, white-box). Black-box: <package>_test package name.

Build and Quality Gates

Run templ generate before every build. Never use go run.

templ generate && go build -o bin/ingatan-webui ./cmd/ingatan-webui
./bin/ingatan-webui --help

Cross-compile targets (run templ generate once before all):

templ generate
GOOS=linux GOARCH=arm64 go build -o bin/ingatan-webui-arm64 ./cmd/ingatan-webui
GOOS=linux GOARCH=amd64 go build -o bin/ingatan-webui-amd64 ./cmd/ingatan-webui

Quality gate — all must pass before task complete:

templ generate && go fmt ./... && go mod tidy && go vet ./... && golangci-lint run && go test ./... && go build -o bin/ingatan-webui ./cmd/ingatan-webui && ./bin/ingatan-webui --help

Failure policy: format/tidy auto-fix; vet/lint errors/test failures/build failures — must fix before proceeding.

golangci-lint v2 (.golangci.yml — v2 format required):

• formatters: section for gofmt/goimports (NOT under linters:)
• No gosimple (absorbed into staticcheck)
• settings: not linters-settings:

Code Design Review (before every git commit)

• No business logic in handlers — call ingatan REST API, render response as HTML
• All ingatan API calls go through internal/client/ — no direct HTTP in handlers
• Session cookie is HttpOnly + Secure + SameSite=Strict — JWT never exposed to browser JS
• CSRF token validated on all state-changing form submissions (POST/PUT/PATCH/DELETE)
• Error handling complete — no swallowed errors; render error page/fragment on API failure
• All exported types/functions have doc comments
• No hardcoded ingatan server URLs, session secrets, or env-specific values
• templ generate produces no errors; *_templ.go files are up to date
• HTMX fragment endpoints (/ui/*) return HTML fragments only — not full pages
• Happy path + error paths tested (API error, auth failure, session expiry, CSRF rejection)

Fix policy: critical/important issues (session security, CSRF, credential exposure) — fix before commit. Minor (style) — fix if < 5 min, otherwise create follow-up task.

Agent Workflow

1. Understand: Read relevant docs and code first.
2. Plan: Identify affected handler/client/template layers.
3. Red: Write failing tests.
4. Green: Minimal implementation.
5. Refactor: Clean code, run tests after each change.
6. Quality Gates: Run the combined gate command (including templ generate).
7. Design Review: Run checklist, fix critical/important issues.
8. Document: Update documentation/ for architectural changes.
9. Update Status: Update specs/<feature>/status.md — MANDATORY after every task.
10. Final Verify: Re-run quality gates.

CRITICAL: status.md must be updated immediately after each task. Never mark complete until all gates AND design review pass.

Documentation

• documentation/: Internal docs for developers/agents. Required: product-summary.md, product-details.md, technical-details.md. Update on architecturally significant changes.
• support_docs/: User-facing guides, tutorials, troubleshooting.
• README.md: Project overview for both audiences.

Feature Specs Workflow

specs/<feature-name>/
  spec.md           # Requirements and acceptance criteria
  status.md         # CRITICAL: phase tracking — update after every task
  plan.md           # Implementation plan
  tasks.md          # TDD task breakdown
  research.md       # Findings and API notes
  data-dictionary.md
  implementation-notes.md

• Create spec directory before starting work.
• Update status.md after EVERY task — not optional.
• Archive to specs/archive/ when stable.
• Specs are gitignored (local planning artifacts only).

Agent Teams

• Do not specify model when spawning teammates unless the user requests a specific model.

Git

• No AI attribution in commits. No Co-Authored-By: Claude ... or similar trailers.
• bin/, specs/, test artifacts, IDE files must be in .gitignore.
• Compiled templ files (*_templ.go) ARE committed — generated Go source, not build artifacts.

Project Structure

cmd/ingatan-webui/main.go        # Entry point + router setup
internal/
  handler/                       # Full-page handlers (GET /*) and HTMX fragment handlers (GET|POST /ui/*)
  client/                        # ingatan REST API client
  session/                       # HttpOnly cookie session, JWT management, CSRF
  config/                        # Config loader + env var merging (~/.ingatan-webui/config.yaml)
  webui/
    templates/layout/            # base.templ, nav.templ
    templates/pages/             # Full-page templ templates
    templates/fragments/         # HTMX partial templ templates
    static/                      # Pre-built CSS, vendored HTMX + Alpine.js (go:embed)
documentation/  support_docs/  specs/  bin/