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