Agent Context Guide

Agent Context Guide

Map for AI coding agents working on QASight (qasight, CLI qasight): which note to read before touching what, so you don't have to scan the whole codebase. Adopting QASight in another project instead? Use the Setup Prompts.

Where to look

• Architecture & flow: System Diagram is the one-picture view. Before changing execution logic, runtime state or core modules, read Architecture Overview and Deep Dive - Execution Logic. Don't guess the lifecycle phases.
• CLI changes: before adding or changing a command, flag or exit code, read Command Reference and Troubleshooting and Error Codes. tests/contract/qasight/test_cli_docs_drift.py fails if the reference documents a command that doesn't exist. A new qasight.yaml key also goes in qasight/config/json_schema.py (then run python scripts/export_config_schema.py).
• CI and releases: CI-CD Pipeline Setup, QA Strategies § CI and streaming output, and the publishing guides (PyPI, Docker images, Artifactory).
• Team server and qasight ingest: Team Server and Ingest and Team Server - 2026-10-22. Dockerfile.qasight-server, deploy/server/ and scripts/team_server_smoke.sh change together. Where a stage's process runs (host or the container runner service) is qasight/engine/backends/; read Throwaway Stage Containers - 2026-10-24 before touching it or Dockerfile.qasight-runner-service.
• Resource pools and qasight lease: Shared Resource Pools and Resource Pools and Leases - 2026-10-26. Code in qasight/resources/, the API in qasight_api/routes/resources.py.
• Pages demo: GitLab Pages Demo (covers GitHub Pages too).
• Reporting: QA Strategies § How results are logged and surfaced and the reporter section of Command Reference.
• E2E harness: E2E Harness Operations Guide.
• Docs vault, wiki and site: vault schema, Docs Vault and Wiki Sync and Docs Site. Images go under docs/assets/ and must be embedded from a note to reach Obsidian and the wiki. A new note gets a nav entry in mkdocs.yml to show in the site's menu.
• Getting started: Getting Started is tested by examples/getting-started/ in CI. A change to the commands or config it shows updates both.
• UI: the React frontend in frontend/ is the only UI; its API types are generated from FastAPI's OpenAPI schema.
• Delta semantics: Delta Comparison Policy.
• Design decisions: Specs & ADRs.
• Open debt and next steps: Technical Debt Tracker, Product Roadmap.
• History: dated plans, audits and phase checklists are in Archive. They describe the code as it was, not as it is.

Rules

The full conventions (frontmatter, ingest / query / lint, the log) are in the vault schema; python scripts/docs_vault.py lint checks them.

1. Read before writing. Check the relevant note above before refactoring core architecture or changing a CLI argument.
2. Keep docs in step. If you change a CLI command, execution state logic or infrastructure setup, update the matching note under docs/ in the same pull request. Bump the note's updated date.
3. Point, don't paste. If a note already explains something, link to it instead of repeating it.
4. Links. Use standard relative markdown links with spaces encoded as %20 (e.g. [Command Reference](../CLI%20Commands/Command%20Reference.md)), so they work on GitHub and in Obsidian. When you move or rename a note, update the links to it and Index in the same change.

---

Generated from docs/Prompts & Snippets/Agent Context Guide.md. Edit it there; changes made in the wiki are overwritten.