testeiya 0.2.1 → 0.3.1-0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Testomat.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,246 +1,384 @@
 <p align="center">
-  <a href="https://testomat.ai/testeiya/">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/npm/testeiya/assets/testeiya-logo-dark.svg">
-      <img src="https://cdn.jsdelivr.net/npm/testeiya/assets/testeiya-logo.svg" alt="Testeiya logo" width="140">
-    </picture>
-  </a>
+  <img src="https://raw.githubusercontent.com/testomatio/testeiya-app/main/assets/testeiya-cli-logo.png" alt="Testeiya" width="220">
 </p>
 
-<h1 align="center">Testeiya CLI</h1>
+# Testeiya
 
-<p align="center">
-  A QA-focused AI agent for your terminal and CI.<br>
-  Built on the <a href="https://github.com/can1357/oh-my-pi">oh-my-pi</a> harness (a fork of <a href="https://github.com/badlogic/pi-mono">Pi</a>).
-</p>
+[![npm](https://img.shields.io/npm/v/testeiya)](https://www.npmjs.com/package/testeiya)
+[![licence](https://img.shields.io/npm/l/testeiya)](LICENSE)
 
-<p align="center">
-  <a href="https://testomat.ai/testeiya/">Website</a> ·
-  <a href="https://www.npmjs.com/package/testeiya">npm</a> ·
-  <a href="https://testomat.io">Testomat.io</a>
-</p>
+An agent, app, and the goddess of testing.
 
-```text
-████████ ███████ ███████ ████████ ███████ ██████ ██    ██  █████
-   ██    ██      ██         ██    ██        ██    ██  ██  ██   ██
-   ██    █████   ███████    ██    █████     ██     ████   ███████
-   ██    ██           ██    ██    ██        ██      ██    ██   ██
-   ██    ███████ ███████    ██    ███████ ██████    ██    ██   ██
+Testeiya is an autonomous QA agent. It reacts to triggers — a pull request, a new
+issue, a failed test run, a deploy — runs exactly one analysis, and delivers its
+verdict where your team works: a PR comment, a markdown report, or a Testomat.io
+project. There is no interactive mode and no human in the loop. That is the point:
+you wire it into CI once, and every event that should get QA thinking gets it.
 
-                 AI Testing Agent · Testomat.io
-```
+It ships as a desktop app, a web app, and the command-line agent in this repository.
 
-## What is Testeiya CLI?
+| Folder | What it is |
+|---|---|
+| `prompt/` | System-prompt fragments: the agent's role, rules, tool guidance, Testomat.io operating rules, and the report contract |
+| `skills/` | The manifest of skills the agent can invoke. Every folder is fetched from its own upstream repository |
+| `src/` | The `testeiya` command-line agent (Node) |
 
-Testeiya is an AI testing agent: point it at a project and it analyzes test suites, finds coverage gaps, writes and improves test cases, and syncs them with [Testomat.io](https://testomat.io).
+The desktop and web harness is not open source. That covers the servers, session management, sync, and UI.
 
-**Testeiya CLI** is the terminal edition of that agent. It is made to:
+## Install
 
-- **run in your terminal** — an interactive agent in the current working directory
-- **run in non-interactive environments like CI** — everything is configurable through environment variables and config files, with no GUI required
+Requires Node 22.19 or newer, an LLM provider key, and a model.
 
-It reads your codebase freely while keeping writes and destructive commands locked down by default, so you can safely point it at any project.
+```bash
+npx testeiya doctor
+```
 
-> Looking for a visual app instead? **Testeiya Desktop** is a separate chat application built on the same agent. Testeiya CLI is the official name of this terminal tool — the two are not the same thing. Learn about both at [testomat.ai/testeiya](https://testomat.ai/testeiya/).
+`doctor` reports which key won, which skills loaded, and whether Testomat.io is reachable — without spending a token.
 
-## Quick start
+The key comes from the environment (`OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`,
+`OPENAI_API_KEY`, `GEMINI_API_KEY`), from `~/.testeiya/.env`, or from
+`~/.testeiya/auth.json`. That last file is the one the desktop app's Settings
+dialog writes, so configuring it once covers both.
 
-Requires [Bun](https://bun.sh) 1.3+.
+There is no default model. Name one with `--model <provider>/<id>` or
+`TESTEIYA_MODEL`. CI usually has neither set, so a run that resolves no model
+exits `2` rather than picking one for you.
 
 ```bash
-bunx testeiya
+export TESTEIYA_MODEL=openrouter/anthropic/claude-sonnet-5
+testeiya models anthropic   # list what your key can reach
 ```
 
-Or install it globally:
+## How it runs
 
 ```bash
-bun add -g testeiya
-testeiya
+testeiya task "<task>"     # run one task, deliver a report, exit
+testeiya ask "<question>"  # answer a question, no report
+testeiya skills            # list the skills bundled with this package
+testeiya sessions          # list saved sessions for this folder
 ```
 
-Bring an API key for your LLM provider, or sign in with an AI coding subscription you already have — see [Providers](#providers) below.
+The agent runs one task and exits. Progress goes to stderr, so a run drops into CI as-is:
 
-Then ask it things like:
+| Exit code | Meaning |
+|---|---|
+| `0` | pass, or a positive verdict from the agent |
+| `1` | failed run, or a negative verdict — findings that need a human |
+| `2` | bad usage |
+| `130` | interrupted |
 
-- "Analyze the test suite in this project"
-- "Find untested code paths in src/controllers"
-- "Generate test cases for the auth module"
-- "Find duplicate test cases and suggest which to remove"
+Pass `--exit-zero` when a negative verdict must not fail the job. A broken run
+still exits `1`, bad usage still exits `2`, and the verdict is still in the
+report and in the run envelope for anything that wants to gate on it.
 
-Multi-line pastes (API docs, specs, requirements) go straight into the prompt.
+A task can come from stdin too:
 
-## Providers
+```bash
+cat issue-42.md | testeiya task --output report.md
+```
 
-Testeiya is not tied to a single LLM vendor, and it takes two kinds of access: pay-as-you-go API keys, or the AI coding subscription you may already have.
+Every command takes `--json` for machine-readable output of the run envelope
+(verdict, reason, tokens, session id). `testeiya --help` lists all options;
+`testeiya help` is the full guide.
 
-### API platform access
+## Scenarios
 
-Pick whichever provider your team already uses, export its API key, and go:
+Each scenario below is a single unattended run. Nobody answers questions; the
+agent reads what the trigger gives it and acts on its own judgement. If its
+verdict is negative, the job fails — that failure *is* the signal.
 
-| Provider | `provider.name` | API key variable |
-| -------------------- | ------------ | -------------------- |
-| OpenRouter (default) | `openrouter` | `OPENROUTER_API_KEY` |
-| OpenAI | `openai` | `OPENAI_API_KEY` |
-| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` |
-| Google Gemini | `google` | `GEMINI_API_KEY` |
-| Groq | `groq` | `GROQ_API_KEY` |
-| Mistral | `mistral` | `MISTRAL_API_KEY` |
-| xAI | `xai` | `XAI_API_KEY` |
-| Azure OpenAI | `azure-openai-responses` | `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_BASE_URL` |
-| Ollama (local) | `ollama` | not required |
+### Grill a pull request
 
-Many more work out of the box (Together, Cerebras, Moonshot, LM Studio, …), and any OpenAI-compatible endpoint — a vLLM or LiteLLM gateway, a corporate proxy — can be plugged in through `provider.baseUrl`.
+Every PR gets a QA review before merge. The agent loads the branch's diff,
+analyzes it through the `qa-thinking` skill — edge cases, negative flows,
+abuses, data-consistency risks — and posts the findings as a PR comment:
 
-Keys can also live in a `.env` file in the working directory or in `~/.testeiya/.env`.
+```bash
+git fetch origin "$PR_BRANCH"
+git checkout "$PR_BRANCH"
+testeiya task "Review this pull request as a QA engineer. What could go wrong?" \
+  --output gh:pr-comment --output review.json
+```
 
-### Subscriptions
+Exit code `1` means the agent found real risk, so you can gate the merge on it.
 
-Already paying for an AI coding plan? Sign in with it instead of managing API keys — type `/login` inside the agent and pick the account:
+### Write test cases from a pull request
 
-| Subscription | `provider.name` |
-| ---------------------------- | ---------------- |
-| Claude Pro / Max (Anthropic) | `anthropic` |
-| ChatGPT / Codex (OpenAI) | `openai-codex` |
-| GitHub Copilot | `github-copilot` |
-| Gemini (Google account) | `google-gemini-cli` |
-| Cursor | `cursor` |
-| Kimi Code | `kimi-code` |
+Same trigger, different deliverable: the `qa-write-test-cases` skill turns the
+change into test cases in Testomat.io markdown format, written as a build
+artifact ready to commit or import:
 
-…plus GitLab Duo, Qwen, Z.ai and other coding plans — `/login` shows everything available. Credentials are stored locally and refreshed automatically.
+```bash
+testeiya task "Create test cases covering the changes in this pull request" \
+  --output testcases/
+```
 
-To switch providers or models at any time, type `/model` inside the agent, or set `provider.name` and `provider.model` in the config file (see [Configuration](#configuration)).
+With `TESTOMATIO` and the project id set, add
+`sync them to Testomat.io` to the task and they land straight in the TMS via
+`sync-test-cases-with-tms`.
 
-## Connect to Testomat.io
+### Create test cases from a new issue
 
-Testeiya works standalone, but connecting a [Testomat.io](https://testomat.io) project unlocks test management: pulling and pushing test cases, browsing runs, and the Testomat.io MCP tools.
+A requirements text arrives from the issue tracker — piped in, no human
+summarizing it first. The agent writes a checklist and test cases from it:
 
-Interactively, type `/connect` inside the agent and pick a project.
+```bash
+gh issue view 57 --json title,body -q '.title + "\n\n" + .body' \
+| testeiya task --output testcases/issue-57.md
+```
 
-In CI or scripts, pass the project token via environment variables:
+### Explore a deployed app with Explorbot
+
+After a deploy, point [Explorbot](https://github.com/testomatio/explorbot) — the
+autonomous browser-testing CLI the agent drives through the `explorbot-*`
+skills — at the staging URL. It researches, plans, and tests the live app in
+its own browser, then reports what broke:
 
 ```bash
-export TESTOMATIO=tstmt_your-project-token
+testeiya task "Run explorbot against https://staging.example.com, max 10 tests, report failures" \
+  --output explorbot-report.md
 ```
 
-## Skills
-
-Testeiya ships with a curated skill library, loaded automatically:
+### Repair failing tests after a red build
 
-- **Test management** (Testomat.io) — write and improve test cases, detect duplicates, analyze coverage, review requirements, sync cases with the TMS
-- **Test automation** (Testomat.io) — automate manual test cases, debug flaky tests, set up reporters and PR testing
-- **Frameworks** — CodeceptJS (writing, debugging, migrations from Cypress/Protractor/TestCafe/Selenium), Playwright best practices and the Playwright browser CLI
-- **Testomat.io docs** — the full product documentation, bundled and searchable, so platform questions are answered from the docs
+On a failed CodeceptJS run, the `ci-fix-tests` skill attempts safe fixes only —
+locator drift, missing waits — reruns just the failing scenarios, rolls back any
+edit that did not help, and always writes `output/ci-fix.md` for the next job:
 
-Add your own: drop a folder with a `SKILL.md` into `~/.testeiya/skills/` (all projects) or `<project>/.testeiya/skills/` (one project). Type `/skills` in the agent to list what's loaded.
+```bash
+testeiya task "Fix the failed CodeceptJS tests using ci-fix-tests. No refactors." \
+  --no-session
+```
 
-## Slash commands
+### Audit the test suite on a schedule
 
-| Command | Purpose |
-| ---------- | ------------------------------------------------ |
-| `/connect` | Link a Testomat.io project and load its MCP tools |
-| `/project` | Switch the active Testomat.io project |
-| `/model` | Switch the LLM provider and model |
-| `/login` | Sign in with an AI subscription account |
-| `/skills` | List loaded skills |
-| `/help` | Show all commands |
+Nightly, the agent walks the Testomat.io project and reports gaps — suites with
+no tests, cases gone stale against the current code, coverage holes:
 
-## Running in CI
+```bash
+TESTOMATIO=tstmt_xxx testeiya task \
+  "Audit this project: which suites have no automated tests, and which manual cases look automatable?" \
+  --output audits/$(date +%F).md
+```
 
-Testeiya CLI is built to run where no human is watching. The default permission model (reads allowed, writes and bash blocked) makes it safe to run against a checked-out repository.
+## CI setup
 
-Each example below uses a different LLM provider — any provider works on any CI; just export the matching API key variable.
+Testeiya needs three things in any CI system: a provider key, a model name, and
+the checkout of whatever the task reads. Everything else is standard.
 
 ### GitHub Actions
 
+GitHub runners ship the [GitHub CLI](https://cli.github.com), so posting back to
+the PR is one flag. `GITHUB_TOKEN` authenticates it; keep the LLM key in
+repository secrets.
+
 ```yaml
-- uses: oven-sh/setup-bun@v2
-- run: bunx testeiya
-  env:
-    OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
-    TESTOMATIO: ${{ secrets.TESTOMATIO_TOKEN }}
+name: qa-review
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  grill:
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ github.token }}
+      OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+      TESTEIYA_MODEL: openrouter/anthropic/claude-sonnet-5
+      # optional, for scenarios that touch Testomat.io
+      TESTOMATIO: ${{ secrets.TESTOMATIO }}
+      TESTOMATIO_PROJECT_ID: my-project
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npx testeiya@latest doctor
+      - run: |
+          npx testeiya@latest task \
+            "Review this pull request as a QA engineer. What could go wrong?" \
+            --output gh:pr-comment --output review.json
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: review
+          path: review.json
 ```
 
+The same shape works for the other scenarios: trigger on `issues` and pipe the
+body in for test-case generation, or run on a `schedule` for the nightly audit.
+
 ### GitLab CI
 
+GitLab runners do not ship `gh`, so the report goes to job artifacts — visible
+in the merge request pipeline page. Exit code `1` fails the job and blocks the
+merge when you mark it required.
+
 ```yaml
-testeiya:
-  image: oven/bun:1
-  script:
-    - bunx testeiya
+qa-review:
+  image: node:22
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
   variables:
-    OPENAI_API_KEY: $OPENAI_API_KEY
-    TESTOMATIO: $TESTOMATIO_TOKEN
+    TESTEIYA_MODEL: openrouter/anthropic/claude-sonnet-5
+    TESTOMATIO_PROJECT_ID: my-project
+  script:
+    - git fetch origin $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
+    - npx testeiya@latest doctor
+    - npx testeiya@latest task
+        "Review this merge request as a QA engineer. What could go wrong?"
+        --output review/report.md --output review/envelope.json
+  artifacts:
+    when: always
+    paths:
+      - review/
+  parallel:
+    # secrets go to Settings > CI/CD > Variables:
+    #   OPENROUTER_API_KEY (masked), TESTOMATIO (masked, protected)
 ```
 
-### Bitbucket Pipelines
+For posting back to the merge request, hand the envelope's report to GitLab's
+API in a follow-up step, or install `gh` plus a token mirror if the project is
+also on GitHub.
 
-```yaml
-pipelines:
-  default:
-    - step:
-        name: testeiya
-        image: oven/bun:1
-        script:
-          # ANTHROPIC_API_KEY and TESTOMATIO are set as secured repository variables
-          - bunx testeiya
-```
-
-### Jenkins
-
-```groovy
-pipeline {
-  agent { docker { image 'oven/bun:1' } }
-  environment {
-    MISTRAL_API_KEY = credentials('mistral-api-key')
-    TESTOMATIO = credentials('testomatio-token')
-  }
-  stages {
-    stage('testeiya') {
-      steps {
-        sh 'bunx testeiya'
-      }
-    }
-  }
-}
-```
-
-### Azure Pipelines
+### Anywhere else
 
-```yaml
-steps:
-  - script: |
-      curl -fsSL https://bun.sh/install | bash
-      export PATH="$HOME/.bun/bin:$PATH"
-      bunx testeiya
-    env:
-      AZURE_OPENAI_API_KEY: $(AZURE_OPENAI_API_KEY)
-      AZURE_OPENAI_BASE_URL: $(AZURE_OPENAI_BASE_URL)
-      TESTOMATIO: $(TESTOMATIO_TOKEN)
+Any scheduler that can run a container works — the contract is just stdin,
+stdout, and an exit code:
+
+```bash
+echo "Audit the checkout suite for gaps" | testeiya task --output audit.md
+case $? in
+  0) echo "clean" ;;
+  1) echo "findings need review" ;;
+esac
 ```
 
-## Configuration
+## Where the report goes
+
+`--output` names a destination and can repeat. Without one the report goes to stdout.
+
+```bash
+testeiya task "<task>" --output report.md --output run.json --output gh:pr-comment
+```
+
+| Destination | What happens |
+|---|---|
+| `report.md` | the agent writes the report there |
+| `run.json` | the run envelope: verdict, reason, report, tokens, session id |
+| `gh:pr-comment` | posted on this branch's pull request |
+| `gh:pr#123` | posted on that pull request |
+
+Posting uses the GitHub CLI and resolves the PR number from `GITHUB_EVENT_PATH`,
+`GITHUB_REF`, or `gh pr view` — so inside Actions it just works. Every
+destination is checked before the run starts, so a missing `gh` costs no tokens.
+
+`--footer "<text>"` adds a line under a posted comment, and nowhere else. It is
+what turns a report into a conversation: tell the reader how to answer, and let
+the workflow feed their reply back into the same session.
+
+```bash
+testeiya task "Review this pull request" \
+  --output gh:pr-comment \
+  --footer "> You can reply to this comment by typing /testeiya"
+```
+
+## Sessions
+
+Runs are saved under `~/.testeiya`, so a follow-up picks up where the last one
+stopped. A resumed run reuses its session's model.
+
+```bash
+testeiya task "Review the checkout suite" --name checkout-review --output report.md
+testeiya task "Now write the missing cases" -c
+testeiya sessions
+testeiya task "<task>" --resume <id>
+```
+
+Pass `--name` to label a session and `--no-session` to save nothing.
+
+In CI, `--session <label>` is the one to reach for: it continues the session
+with that label, and starts it the first time, so a job that runs again and
+again needs no "does it exist yet" branch. Give each thread its own label, and
+carry `~/.testeiya` between rounds with the runner's cache. `--no-session` keeps
+runners stateless when continuity is not wanted.
+
+```bash
+testeiya task "Review the new commits" --session "pr-42" --output gh:pr-comment
+```
+
+## Testomat.io
+
+Set `TESTOMATIO` to a project API key. The agent can then read and write that
+project's tests, suites, runs and plans through `check-tests` and the REST API.
+
+```bash
+TESTOMATIO=tstmt_xxx testeiya task --project my-project "Which suites have no tests?"
+```
+
+Add the project id and the agent also gets the Testomat.io MCP tools. The id
+comes from `--project` or from `TESTOMATIO_PROJECT_ID`; the MCP server needs it,
+because a token alone does not say which project to talk to. `TESTOMATIO_URL`
+points at a self-hosted instance.
+
+## Skills
+
+A skill is a folder with a `SKILL.md`. The agent loads them all and invokes the
+ones a task calls for — you never pick a skill explicitly, the task phrasing
+does.
+
+The set is vendored from upstream repositories and moves with every release, so
+ask your own install rather than a list in a README:
+
+```bash
+testeiya skills             # every bundled skill: name and what it is for
+testeiya skills playwright  # filter by name, category or description
+testeiya skills --json      # [{name, group, description}]
+```
+
+Categories today: QA process, test management, test automation, Explorbot,
+Playwright, CodeceptJS.
+
+Sources are declared in `skills/skills.yaml` and pinned in
+`skills/skills.lock.json`. The vendored folders are deliberately not committed —
+they belong to their authors, under their own licences. A clone has the manifest
+and nothing else; `node scripts/vendor-skills.js` fills the tree. Every release
+runs it, so the published `testeiya` package ships each skill as current on
+release day.
+
+`skillsOverride` in `src/session.ts` keeps only what is found under that tree,
+so an arbitrary clone cannot hand the model its own skills. To add yours, point
+`additionalSkillPaths` at your folder. [EXTENDING.md](EXTENDING.md) covers both hooks.
+
+To propose a new source, add its line to `skills/skills.yaml`. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Building your own agent
+
+The CLI is a thin composition over [pi](https://pi.dev): about 1,500 lines wiring
+the SDK to the prompt and skills here. A fork can add pi extensions and custom
+tools, or swap the one-shot run loop for pi's full interactive TUI.
+[EXTENDING.md](EXTENDING.md) walks through both.
+
+## Contributing
 
-Configuration is layered, lowest to highest priority: built-in defaults, then `testeiya.config.json` in the working directory, then `~/.testeiya/config.json`. The in-app `/model` selection writes to the home file, so it persists across runs.
+Prompt wording is exactly what an outside contributor can improve, and a change
+to it changes how the agent behaves for everyone. Read
+[CONTRIBUTING.md](CONTRIBUTING.md) first. It covers what belongs here and what
+belongs upstream, in the repository that owns a given skill.
 
-All options:
+## Issues
 
-| Option | Default | Purpose |
-| ------------------------- | ------------ | ------- |
-| `provider.name` | `openrouter` | LLM provider id (see [Providers](#providers)) |
-| `provider.model` | — | Model id, as your provider names it |
-| `provider.baseUrl` | provider's own | API endpoint override, for gateways and self-hosted OpenAI-compatible servers |
-| `provider.contextWindow` | `200000` | Context window size the agent budgets against |
-| `provider.maxTokens` | `16384` | Maximum output tokens per response |
-| `thinkingLevel` | `medium` | Reasoning effort: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
-| `permissions.autoAllowRead` | `true` | Auto-approve read-only tools |
-| `permissions.blockWrites` | `true` | Block edit and write tools |
-| `permissions.blockBash` | `true` | Allow only read-only bash commands |
-| `memoryEnabled` | `true` | Per-project agent memory |
-| `testomatioHost` | `https://app.testomat.io` | Testomat.io base URL, for self-hosted instances |
-| `toolGate.activeTools` | — | Per-MCP-server glob patterns of tool names to keep active; the rest load on demand |
+This repository is also the public issue tracker for both surfaces:
 
-API keys are never stored in these files — they come from environment variables or `.env` files (working directory or `~/.testeiya/.env`).
+- Testeiya Desktop app, the packaged desktop application
+- Testeiya CLI, the command-line agent in `src/`
 
-## License
+## Licence
 
-ISC
+[MIT](LICENSE).

package/dist/prompt/context.js

@@ -0,0 +1,79 @@
+import dedent from "dedent";
+import { TESTEIYA_DIR_NAME } from "./vocab.js";
+/** System-prompt section describing the workspace context; "" when none. */
+export function contextPromptSection(entries, folders = []) {
+    if (entries.length === 0 && folders.length === 0)
+        return "";
+    return dedent `
+  <workspace-context>
+    This workspace has context attached — the user (or you, earlier) put it there for a purpose. Consult it before answering, and prefer it over assumptions about the project.
+
+  ${contextLines(entries, folders)}
+
+    ALL of it lives under the hidden \`${TESTEIYA_DIR_NAME}/\` dir: file-search tools skip hidden dirs by default, so search it explicitly (pass hidden:true, or prefix the path with \`${TESTEIYA_DIR_NAME}/\`). Linked folders and cloned repositories are reference material: read them, never modify them. A linked folder is a symlink — wildcard searches do not descend into it; search it with its own path prefix (e.g. \`${TESTEIYA_DIR_NAME}/<name>/\`). Documents under \`${TESTEIYA_DIR_NAME}/requirements\` and \`${TESTEIYA_DIR_NAME}/docs\` are specs and plans — use them when writing or reviewing tests.
+  </workspace-context>
+  `;
+}
+/** Per-prompt notice when the context changed mid-session; appended to the next prompt. */
+export function contextUpdateNotice(entries, folders = []) {
+    if (entries.length === 0 && folders.length === 0) {
+        return dedent `
+    <workspace-context-update>
+      All extra workspace context was removed. Do not rely on it anymore.
+    </workspace-context-update>
+    `;
+    }
+    return dedent `
+  <workspace-context-update>
+    The workspace context just changed. It now contains:
+
+  ${contextLines(entries, folders)}
+
+    This was done for a purpose — take it into account for this and future requests. Remember \`${TESTEIYA_DIR_NAME}/\` is hidden: search it with hidden:true or an explicit path prefix.
+  </workspace-context-update>
+  `;
+}
+function contextLines(entries, folders) {
+    const lines = [];
+    const covered = new Set(entries.map((e) => parentDir(e.path)));
+    for (const f of folders) {
+        if (covered.has(f.path))
+            continue;
+        lines.push(`- \`${f.path}/\` — ${folderPurpose(f.name)}`);
+    }
+    for (const e of entries)
+        lines.push(`- ${describeEntry(e)}`);
+    return lines.join("\n");
+}
+function folderPurpose(name) {
+    if (name === "manual-tests") {
+        return "the project's manual test suites pulled from Testomat.io (*.test.md — THE manual tests of this project)";
+    }
+    if (name === "code")
+        return "reference code added as context";
+    if (name === "requirements")
+        return "requirements and specs";
+    if (name === "docs")
+        return "test planning and strategy documents";
+    if (name === "auto-tests")
+        return "automated test references";
+    return "exploratory testing setup";
+}
+function parentDir(rel) {
+    const idx = rel.lastIndexOf("/");
+    if (idx < 0)
+        return "";
+    return rel.slice(0, idx);
+}
+function describeEntry(e) {
+    const date = e.addedAt?.split("T")[0] ?? "";
+    let from = "";
+    if (e.origin && e.origin !== e.name)
+        from = ` from ${e.origin}`;
+    if (e.kind === "repo")
+        return `\`${e.path}\` — git repository${from} (${date})`;
+    if (e.kind === "folder")
+        return `\`${e.path}\` — local folder${from} (${date})`;
+    return `\`${e.path}\` — document${from} (${date})`;
+}
+//# sourceMappingURL=context.js.map