vault-dash/AGENTS.md

policy:
  subagent_usage:
    required: true
    rules:
      - prefer sub-agents for parallelizable implementation work
      - use sub-agents when implementing independent roadmap items
      - create worktrees for sub-agents working on the same codebase
      - review sub-agent output before merging to main
      - use `agent: implementation-reviewer` for code quality checks
      - use `agent: qa-validator` for end-to-end validation
      - chain sub-agents for multi-step workflows (plan → implement → review)
      - always use sub-agents unless the task is trivial or requires direct interaction

  test_loop:
    required: true
    rules:
      - run the app locally after changes
      - run real tests against the running app
      - for UI work, prefer Playwright/browser-visible checks
      - verify the exact changed route/page

  local_first:
    required: true
    rules:
      - use local Docker/OrbStack before deploy
      - deploy only after local behavior is verified

  confidence:
    rules:
      - browser-visible behavior beats log-only confidence
      - do not treat returned HTML as success if the page still has runtime/UI errors
      - do not claim a feature is live unless the rendered UI consumes it

  development_flow:
    tdd: [red, orange, green]
    build_rule:
      - make build must enforce lint first
      - if build is green, lint is already green

  review:
    required_before_merge: true
    install_tool: review_install_agents
    rules:
      - install review agents with the review_install_agents tool before running the review workflow if needed
      - use the full parallel review flow before merging worktree or sub-agent changes to main
      - do not merge based only on compile/test results

  backlog:
    review_after_each_sprint: true
    source_of_truth:
      - docs/roadmap/ROADMAP.yaml
      - docs/roadmap/backlog
      - docs/roadmap/in-progress
      - docs/roadmap/done
      - docs/roadmap/blocked
      - docs/roadmap/cancelled
    rules:
      - add newly discovered backlog items
      - reorder priorities and dependencies based on new knowledge
      - capture follow-up work explicitly

  compatibility:
    rules:
      - preserve shared domain compatibility across parallel worktrees
      - LombardPortfolio must remain available for strategy/core compatibility until intentionally removed everywhere

learnings:
  nicegui:
    - ui.header must be a top-level page layout element
    - do not nest ui.header inside ui.column or similar containers

  options_page:
    - loading all expiries/chains before first paint can make the page appear broken
    - render fast first, then load incrementally

  nicegui_fastapi:
    - pages should not assume request.app.state is the right access path for shared services
    - prefer an explicit runtime/service registry

  docker_dev:
    - do not mount the whole repo over /app when the image contains required runtime scripts
    - prefer narrower mounts like ./app and ./config

validation_checklist:
  - local Docker stack starts cleanly
  - /health returns OK
  - changed page opens in browser automation
  - no visible 500/runtime error
  - screenshot artifact captured when useful
  - relevant logs checked

gitea_ci:
  repo:
    base_url: "http://tea.uncloud.vpn"
    api_base_url: "http://tea.uncloud.vpn/api/v1"
    owner: "bu5hm4nn"
    name: "vault-dash"
    full_name: "bu5hm4nn/vault-dash"
    ssh_remote: "ssh://git@tea.uncloud.vpn:2223/bu5hm4nn/vault-dash.git"
  auth:
    preferred_method: "tea login"
    notes:
      - "`tea` is already logged in for this repo and should be preferred for API access"
      - "`tea api` works against this Gitea 1.25.5 instance even when higher-level `tea actions` commands are unavailable"
      - A raw token may exist separately, but automation should not assume one unless the user says so
    shell_setup: |
      export GITEA_URL="${GITEA_URL:-http://tea.uncloud.vpn}"
      export GITEA_API="${GITEA_API:-$GITEA_URL/api/v1}"
      export GITEA_REPO="bu5hm4nn/vault-dash"
      tea login list >/dev/null
      command -v jq >/dev/null
  triage:
    preferred_method: "use `tea api` for run/job/log discovery; use the Gitea web UI as fallback"
    tested_on: "2026-04-07"
    tested_behavior:
      - "`tea actions runs list` refuses to run because the server is older than 1.26.0"
      - "`tea api` works and authenticates via the stored tea login"
      - Gitea 1.25.5 exposes Actions run, job, log, workflow, artifact, and runner endpoints in swagger
      - The new server supports `/repos/{owner}/{repo}/actions/runs/{run}/jobs` and `/repos/{owner}/{repo}/actions/jobs/{job_id}/logs`
    response_shape_note:
      - Gitea Actions list endpoints return object wrappers such as `.workflow_runs` or `.jobs`
      - In jq, prefer `(.workflow_runs // .)` for runs and `(.jobs // .)` for jobs
    default_scope:
      - Prefer latest run for `git rev-parse HEAD`
      - If there is no run for HEAD yet, inspect the latest failed run on the current branch
      - If CI failed, Build and Deploy will not run because deploy is triggered after CI success
  query_recipes:
    list_recent_runs_current_branch: |
      branch="$(git branch --show-current)"
      tea api -l tea.uncloud.vpn "/repos/bu5hm4nn/vault-dash/actions/runs?branch=$branch&limit=20"       | jq '(.workflow_runs // .) | map({id, workflow_id, status, event, head_branch, head_sha, created_at, html_url})'
    latest_run_for_head_sha: |
      branch="$(git branch --show-current)"
      sha="$(git rev-parse HEAD)"
      tea api -l tea.uncloud.vpn "/repos/bu5hm4nn/vault-dash/actions/runs?branch=$branch&limit=50"       | jq -r --arg sha "$sha" '((.workflow_runs // .) | map(select((.head_sha // .commit_sha) == $sha)) | sort_by(.created_at // .run_started_at // .id) | reverse | .[0])'
    latest_failed_run_current_branch: |
      branch="$(git branch --show-current)"
      tea api -l tea.uncloud.vpn "/repos/bu5hm4nn/vault-dash/actions/runs?branch=$branch&status=failure&limit=20"       | jq -r '((.workflow_runs // .) | sort_by(.created_at // .run_started_at // .id) | reverse | .[0])'
    list_jobs_for_run: |
      run_id="<RUN_ID>"
      tea api -l tea.uncloud.vpn "/repos/bu5hm4nn/vault-dash/actions/runs/$run_id/jobs"       | jq '(.jobs // .) | map({id, name, status, conclusion, started_at, completed_at})'
    first_failed_job_for_run: |
      run_id="<RUN_ID>"
      tea api -l tea.uncloud.vpn "/repos/bu5hm4nn/vault-dash/actions/runs/$run_id/jobs"       | jq -r '((.jobs // .) | map(select((.conclusion // .status) == "failure" or .status == "failure")) | sort_by(.started_at // .id) | .[0])'
    download_job_log: |
      job_id="<JOB_ID>"
      tea api -l tea.uncloud.vpn "/repos/bu5hm4nn/vault-dash/actions/jobs/$job_id/logs"
  viewing_job_logs:
    web_ui:
      url: "http://tea.uncloud.vpn/bu5hm4nn/vault-dash/actions"
      steps:
        - Navigate to Actions tab in the Gitea UI
        - Open the run from its `html_url` returned by `tea api`
        - Expand the failing job (lint/test/type-check/build/deploy)
        - Click the failed step to inspect detailed logs
    api:
      preferred_cli: "tea api"
      notes:
        - High-level `tea actions` commands may be version-gated by the CLI
        - "`tea api` is the stable fallback for this Gitea instance"
  workflows:
    CI:
      file: ".gitea/workflows/ci.yaml"
      jobs: [lint, type-check, test]
      triggers: [push main, pull_request main]
    Build_and_Deploy:
      file: ".gitea/workflows/deploy.yaml"
      jobs: [build, deploy]
      triggers:
        - workflow_run after CI succeeds on main
        - manual workflow_dispatch
  common_failures:
    missing_dependency:
      symptom: "ModuleNotFoundError: No module named 'X'"
      fix:
        - Add runtime deps to requirements.txt
        - Add dev/test tooling deps to requirements-dev.txt
        - CI installs requirements-dev.txt, so keep CI-critical deps there
    playwright_version_drift:
      symptom: "Playwright browser/package mismatch or local vs CI behavior differs"
      fix:
        - Keep Python Playwright pinned in requirements-dev.txt
        - Keep the pin aligned with `.gitea/workflows/ci.yaml` Playwright container image tag
    tea_version_gate:
      symptom: "`tea actions ...` says the server is older than 1.26.0"
      fix: "Use `tea api` directly against the Actions endpoints instead of high-level tea subcommands"
    type_error:
      symptom: "error: Incompatible types..."
      fix: "Run `mypy app/core app/models app/strategies app/services app/domain --show-error-codes --show-traceback` locally to reproduce"
    test_failure:
      symptom: "FAILED test_name"
      fix: "Run failing test locally with `pytest -xvs <test_path_or_nodeid>`"

pre_merge_checklist:
  - run `pytest tests/ -v --tb=short` locally and ensure all new/changed tests pass
  - run `/review` to get implementation review and QA validation
  - verify CI passes on Gitea (lint, test, type-check, build, deploy)
  - address all review comments before merging to main