testeiya 0.8.1 → 0.10.0

package/skills/testomatio/requirements/detect-product-mismatches/references/layout.md

@@ -0,0 +1,93 @@
+# Mismatches layout
+
+Reads catalogs (layout owned by `catalog-features`) and feature pages (owned by `wiki-from-code`); changes them only through those skills (SKILL.md › 2. Catalogs). Writes mismatch pages into `mismatches/`
+
+```
+mismatches/                  # output folder
+  README.md                  # sitemap; one line each
+  sources/
+    README.md                # every catalog here: name, type, role, link, Date
+    {name}/                  # source name
+      features/              # feature pages (wiki-from-code), when present
+        .catalog/            # internal: `catalog-features` skill output
+  mismatches/
+    README.md                # index
+    {mismatch}.md            # one mismatch per disagreement, every compared source
+```
+
+## Formatting
+
+Every page: `# Title`, then a breadcrumb that matches folders (links to the parent pages only), then the body. Mismatch pages: no breadcrumb. Relative links to pages in the output folder and to repo paths; source features as key + URL.
+
+## Kinds
+
+| Kind                | Meaning                                                                      | Where       |
+| ------------------- | ---------------------------------------------------------------------------- | ----------- |
+| Differs             | Sources disagree on one behavior: values, conditions, roles, labels, flow    | Page        |
+| Not implemented     | Behavior from another source that the code lacks                             | Page        |
+| Missing in {source} | Feature a source is silent on, within its catalog Scope (SKILL.md › Sources) | README list |
+
+## README
+
+`mismatches/README.md` missing → create it: `# Mismatches`, breadcrumb. Write the mismatches list.
+
+1. Compared: one row per source: name, role, scope, history, catalog link, Date (code: baseline commit). Product version. Check date.
+2. Differs, Not implemented: one list per kind, highest impact first: page link + impact level + sources + likely cause.
+3. Missing features: one list per silent source (Not implemented, Unspecified, Undocumented, Missing in {source}): feature + where found (catalog feature links) + where searched.
+4. Open questions: vague behaviors, unread content, or unclear Scope that blocks a comparison.
+
+## Page
+
+A reader learns what disagrees from the first lines, without opening the sources.
+
+File name: follow existing file name pattern or kebab-case of the title by default.
+
+- `# Title`: the behavior in question, as the user meets it.
+- `Feature:` the feature area › title; link to its feature page in `features/`, when present.
+- `## Difference`: first a one-sentence summary of how they differ, then one bullet per side, code first when compared; sources that agree grouped on one bullet. Each bullet: the sources (key or name), then their behavior. Write each side so it is clear alone: the condition, then what the user gets. Not implemented: the code bullet says what is missing and where it was searched.
+- `## Impact`: level first: **High** (users blocked, data or money wrong), **Medium** (a workaround exists), **Low** (wording, cosmetic). Then who meets it, when, and what they see or cannot do.
+- `## Likely cause`: SKILL.md › Likely cause, with the dates that decide it.
+- `## Solution`: suggested fix, from the likely cause: Bug → change the code; Stale requirement → update the requirement; Stale docs → update the docs; Decide → the options for the product owner.
+- `## Sources`: evidence, one row per compared source; Code row always, first, when code is compared.
+- Other info required to explain the mismatch.
+
+### Example
+
+```markdown
+# Expired cards at checkout
+
+Feature: [Checkout › Pay with saved card](../sources/code/features/checkout/pay-with-saved-card.md)
+
+## Difference
+
+The code lists expired saved cards at checkout, greyed out; Confluence says they are not listed.
+
+- **Code, PAY-112:** Expired saved cards are listed at checkout, greyed out and not selectable.
+- **Confluence "Saved cards":** Expired saved cards are not listed at checkout.
+
+## Impact
+
+Low. A customer with an expired card sees it greyed out at checkout. Support answers based on Confluence say it should not appear.
+
+## Likely cause
+
+Stale requirement: PAY-112 (2026-08-28) changed the behavior after the Confluence page (2026-01-10).
+
+## Solution
+
+Update the Confluence page "Saved cards": expired saved cards are listed at checkout, greyed out and not selectable.
+
+## Sources
+
+| Source                 | Says                                                  | Link                                             | Updated    |
+| ---------------------- | ----------------------------------------------------- | ------------------------------------------------ | ---------- |
+| Code (actual)          | Expired saved cards are listed, greyed out            | `src/checkout/cards.ts:48-61`                    | 2026-08-30 |
+| Jira (intended)        | PAY-112: Expired saved cards are listed, not selectable | [PAY-112](https://example.atlassian.net/...)   | 2026-08-28 |
+| Confluence (intended)  | Expired saved cards are not listed                    | [Saved cards](https://example.atlassian.net/...) | 2026-01-10 |
+| User docs (documented) | silent                                                | Searched: docs/payments/, site search "expired"  |            |
+```
+
+- `Says`: the source's behavior, as [features.md](features.md) › Behaviors describes; `silent` when it has none.
+- `Link`: repo file: `path:lines`; issue: key + URL; page: title + URL, with the heading when the page is long; silent: where searched.
+- `Updated`: the date read at the source (SKILL.md › Likely cause).
+- Superseded issues of a source with history: omit, or mark `superseded by {key}` when it explains the mismatch.

package/skills/testomatio/requirements/wiki-from-code/SKILL.md

@@ -1,124 +1,111 @@
 ---
 name: wiki-from-code
 description: >-
-  Builds and refreshes a product wiki from the application source code (implicit requirements).
-  Optionally attaches issue-tracker task/issue/story links.
-  Use when the user asks to build or refresh the wiki/requirements/specification/docs from code, or to catalog existing functionality.
+  Builds a product wiki from the application source code or updates it after large code changes (release, refactor, many merged PRs).
+  Records mismatches between code and claims about it (comments, docstrings, developer docs, API specs, configs).
+  Use when the user asks to build or update the wiki/requirements/specification/docs from code.
 metadata:
   author: Testomat.io
-  version: 1.0.0
+  version: 2.0.0
 ---
 
 # Wiki from code
 
-Wiki of **how the product works now**. Bootstrap from code. Refresh when the code changes.
+Wiki of **how the product works now**: one page per feature, listing its behaviors, and mismatches between the code and other repo claims.
 
-We call this "wiki" as the closest term to what we are building. But user may ask for "requirements" or "specification" or "docs" or something similar.
+Output folder:
+  - default: `wiki/` (in the repo root)
+  - or given by calling skill or the user
+  - all paths are relative inside the output folder
+  - if there is `features-catalog/` dir → move it to `features/.catalog/`
 
-**Implicit** requirements means inferred from code. **Explicit** requirements means from issues/tasks/docs etc.
-
-Decide audience once:
-
-| Audience | Human wiki |
-| --- | --- |
-| End users (default, preferred) | Behavior and acceptance only. No file paths, types, stack, or protocol internals. |
-| Callers who are not end users (API, job, contract etc.) | Technical entry could be treated as requirements. |
+**Mismatch** is a disagreement between code and a claim about it (comment, docstring, developer docs, API spec, config, infra, test). They could differ, be not implemented, not used, etc.
 
 ## Modes
 
-Pick one. If unclear, **bootstrap** when `wiki/` is missing, else **refresh**.
-
-| Mode | When |
-| --- | --- |
-| `bootstrap` | First wiki from this repo |
-| `refresh` | Code moved; update implicit pages + catalog |
-
-Default root: `wiki/` (or the user’s path).
-
-Move from **overview** to **details**. Do not write feature pages before the tree exists.
+| Mode     | When                                                                                    |
+| -------- | --------------------------------------------------------------------------------------- |
+| `build`  | No `features/` or baseline in the root `README.md`, no git, or the user asks to rebuild |
+| `update` | `features/` and baseline exist: change only what the code changed since the baseline    |
 
 ## Steps
 
 ```
-- [ ] 1. Catalog (shallow)
-- [ ] 2. Tracker links? (ask; optional)
-- [ ] 3. Overview tree (indexes)
-- [ ] 4. Dive each area (one subagent each)
+- [ ] 1. Catalog
+- [ ] 2. Indexes
+- [ ] 3. Feature pages (one subagent per area)
+- [ ] 4. Merge
 - [ ] 5. Validate
 - [ ] 6. Report
 ```
 
-Read [references/layout.md](references/layout.md) before writing files.
+Read [references/behaviors.md](references/behaviors.md) and [references/layout.md](references/layout.md) before writing files.
 
 ## Rules
 
-- Current-state code wins any other source (e.g. docs, tests, config, infra, comments, issues etc). Intended, but not implemented (or implemented differently) behavior goes in `mismatches/` only — never a SHOULD heading on a feature page.
-- Name areas and features from the **product** and user perspective, not the stack or code.
-- Capabilities describe *what the product does*. Catalog records *where that lives in the repo*.
-- Pair capabilities and catalog items (use relative path) (`capabilities/{area}/{feature}.md` ↔ `catalog/{area}/{feature}.yaml`). Feature page: after breadcrumb, relative link to the YAML.
-- Tracker links (tasks, issues, stories, etc.) are optional. **Ask** before adding any. Put them in catalog YAML (`issues`), not on feature pages. Do not invent keys or URLs.
-
-## 1. Catalog (shallow)
-
-The **catalog** is what exists in the product: first a shallow area → feature list, then YAML facts in `catalog/`. Code, test, doc, and issue tracker links live here (`sources`, `tests`, `wiki_path`, `issues`).
-
-From **code** map the product into **areas**, each with a **feature list**. That list *is* the catalog of what exists in the product at this step. Do not draft Requirement/Acceptance or YAML yet.
+- Source is the repository only.
+- **Current-state code wins** over claims (comments, docstrings, developer docs, API specs, configs, tests, etc.). What they claim that the code lacks or does differently goes in `mismatches/` only, never as a "should" on a feature page.
+- Write only paths that exist in the repo. Never guess or build them.
+- Name areas and features from the product and user's perspective, NOT from the code/stack/files/classes/etc.
+- Domain terms (prefer the docs' terms), one term per concept across the wiki.
+- Update catalog file names and content as you get more info about the features.
+- Treat and describe features as end-to-end flows or use cases, not just "actions" from code.
 
-If an area is large, group features into sub-folders at this step. Catalog YAML uses the same relative path as the feature page.
+## 1. Catalog
 
-## 2. Tracker links (optional)
+Run `catalog-features` skill on the repo, same mode, output folder `features/.catalog/`.
 
-**Ask the user** whether to attach issue-tracker links (tasks, issues, stories, etc.) to catalog YAML.
+`update`: get the baseline commit > `git diff --name-status -M {baseline}..HEAD` > process updated/removed files accordingly.
 
-If none of MCP / user-supplied links work: skip with reason. Do not write placeholder tickets.
+## 2. Indexes
 
-Write only into catalog YAML (`issues`). Omit the `issues` key when a feature has no match.
+Write the `features/` indexes before any feature page.
 
-## 3. Overview tree
+[layout.md](references/layout.md)
 
-Write only the indexes first ([references/layout.md](references/layout.md)). Give the tree hierarchy when the product is complex enough. If names are ambiguous, **stop and show the list** before diving.
+## 3. Feature pages
 
-Shared rules live on one page; others link.
+One subagent per area, in parallel (`update`: affected areas only). Each subagent gets: the area, its subareas and catalog features (feature YAMLs), allowed code paths, the Domain from `features/.catalog/README.md`, the rules above, [references/behaviors.md](references/behaviors.md), [references/layout.md](references/layout.md). `update` also: the area's existing pages and mismatches, and its changed features.
 
-## 4. Dive each area
+Subagent, per feature, starting from its catalog links:
 
-For each feature: catalog YAML first (`catalog/{area}/{feature}.yaml`), then the feature page (Requirement / Acceptance). Stubs, unused wiring, and doc-vs-code gaps go in `mismatches/` with all required source links (layout).
+1. In its catalog feature YAML: adds implementation files to `code`, and adds `tests`.
+2. Writes the feature page ([layout.md](references/layout.md) › Feature page): Description, then Behaviors ([behaviors.md](references/behaviors.md)).
+3. Returns one mismatch per disagreement: its kind and every section of a mismatch page ([layout.md](references/layout.md) › Mismatches).
 
-Use `subagent` per area/feature to keep the main agent focused on the helicopter view, subagents focused on the details of one area/feature.
+Subagent writes only inside its area, in `features/` and `features/.catalog/`. Catalog features found missing, misnamed, or misplaced → fix them in the area's catalog files. Anything outside the area (mismatch pages, catalog README, other areas) → return it.
 
-Each subagent gets: area/feature name, allowed paths, audience, [references/layout.md](references/layout.md), "code wins", and whether tracker `issues` are in scope (matched links to write, or omit). Feature pages are Requirement / Acceptance only. Do not rewrite sibling areas except to add the one index line the parent asked for.
+Subagent returns: files added, changed, and removed; mismatches (`update`: also resolved ones); changes outside its area; open questions; catalog errors; terms the Domain lacks.
 
-Subagent returns: files written, mismatches, open questions. Parent merges links and sitemap; then validates.
+## 4. Merge
 
-Exception: a one-line fix on an existing page already in context — no subagent spawn.
+1. Apply the changes subagents returned outside their areas, including links to renamed or moved pages. Terms the Domain lacks → add to the Domain in `features/.catalog/README.md`.
+2. Update every `README.md` in `features/` to list the feature pages that now exist. Write the root `README.md`: a link and purpose for each folder (not `.catalog/`), plus the baseline commit.
+3. Write the mismatch pages subagents returned. Same disagreement from several areas → one mismatch page.
+4. Two terms for one concept → keep one, fix the pages that use the other.
+5. `update`: remove resolved mismatches.
+6. In `mismatches/README.md`, write the mismatches list ([layout.md](references/layout.md) › Mismatches).
 
 ## 5. Validate
 
 ```markdown
 Structure
-- [ ] wiki/README.md is a sitemap; every listed link exists
-- [ ] catalog YAML exists for every feature; every wiki_path exists
-- [ ] catalog/README.md indexes every area; each area catalog README lists its YAML
-- [ ] Area (and group) folders named from the product, not from stack/code
-- [ ] Feature pages use the layout heading order (Requirement, Acceptance); breadcrumbs match folder depth; links are relative
-- [ ] Feature pages link to the paired catalog YAML (relative path)
-- [ ] Feature pages are not mega-dumps (one cluster per page)
-- [ ] Feature pages not overloaded with meta info (it is located in catalog YAML)
-- [ ] Tracker links are in catalog YAML (`issues`); omitted when declined or none matched; no invented keys/URLs
+- [ ] README.md is a sitemap with the baseline commit
+- [ ] Every catalog feature has a feature page, and its feature YAML lists the rest of its implementation files in `code` and its tests in `tests`; `features/` mirrors the catalog's areas and subareas
+- [ ] Every `links`, `code`, and `tests` path exists in the repo
 
 Content
-- [ ] Features described from the user perspective, not the stack/code
-- [ ] Catalog is YAML facts, not a second spec
-- [ ] Current-state Requirement matches code
-- [ ] mismatches/ covers disagreements (between code and other sources)
+- [ ] Every feature page has a Description and at least one behavior under Behaviors; every behavior passes the check in [references/behaviors.md](references/behaviors.md)
+- [ ] Every disagreement between code and claims has a mismatch page
+- [ ] update: resolved mismatches removed; nothing left for deleted code
 ```
 
 ## 6. Report
 
-Where to start from. Results. Mismatches. Huge projects: those three only.
+Where to start. Results (`update`: features added, changed, removed). Mismatches by kind, highest user impact first. Catalog errors. Open questions.
 
 ## Next actions
 
-- Explain a capability in QA language → `qa-explain-behavior`
-- Risk scenarios for a capability → `qa-thinking`
-- Test cases for capability/feature → `qa-write-test-cases`
+- Compare with issues, requirements, user docs → `detect-product-mismatches`
+- Explain a feature in QA language → `qa-explain-behavior`
+- Test cases for a feature → `qa-write-test-cases`

package/skills/testomatio/requirements/wiki-from-code/references/behaviors.md

@@ -0,0 +1,42 @@
+# Behaviors
+
+A behavior is one observable statement about how the product works now: what someone who uses it (end user, admin, API client, integrated system) can do, see, or get, and when. Feature pages list them under Behaviors.
+
+## From code
+
+- Code that runs now and users can reach. Behind a flag or setting that can be turned on → a behavior with that condition.
+- Comments, docstrings, developer docs, API specs, configs, and tests are claims, not behaviors. Where they disagree with the code → `mismatches/`.
+- Never a behavior: internal steps with no visible effect (caching, logging, internal retries), refactoring, helpers.
+
+## Shape
+
+- One behavior per bullet, one sentence, present tense.
+- No `should`, `shall`, `must`, `will`: state it as a fact, present tense.
+- Name who acts or what changes, in domain terms. Never "the system", "it", or "we".
+- Outcome is what the actor can observe (screen, response, file, email, notification), not how the code gets there.
+- Conditions stay in the behavior: role, platform, setting, state.
+- Negative behaviors count: `Viewer cannot delete a project.`
+- Split on "and" when each part can be checked on its own.
+
+## Values and words
+
+- Exact values from the code that runs: limits, defaults, timeouts, sizes, formats.
+- A value read from config or environment: its default, marked `(configurable)`.
+- UI labels and messages verbatim, in quotes; navigation paths with `›`.
+- No class, function, table, file, flag, or library names. Protocol details (endpoints, status codes, fields) only when the API is what users use.
+
+## Examples
+
+| Code                                                | Behavior                                                     |
+| --------------------------------------------------- | ------------------------------------------------------------ |
+| `if (cards.length >= 5) throw new CardLimitError()` | `Customer can save up to 5 cards.`                           |
+| `IDLE_TIMEOUT = env.IDLE_TIMEOUT ?? 1800` (seconds) | `Session expires after 30 min of inactivity (configurable).` |
+| `cache.set(user_id, cards)`                         | Not a behavior: no visible effect                            |
+
+## Check
+
+- [ ] Every reachable behavior in the feature's code is listed
+- [ ] One observable behavior per bullet, present tense, who or what named
+- [ ] Exact values from the code; config values marked `(configurable)`
+- [ ] Domain terms; no stack names unless the API is what users use
+- [ ] No internal steps; nothing taken from comments, docs, or tests

package/skills/testomatio/requirements/wiki-from-code/references/layout.md

@@ -1,94 +1,93 @@
 # Wiki layout
 
-Product-agnostic. Name `{area}` / `{feature}` (and any extra group folders) from **what the product does**, not from the stack. Follow naming rules according to code/language used (kebab-case by default). Same relative path in `capabilities/` and `catalog/`.
+`features/` mirrors `features/.catalog/`: same areas and subareas, one feature page per catalog feature. Every folder has a README. Tree may be updated while the wiki is built.
 
-Default tree is multiple levels under `capabilities/`. Add sub-folders (with required depth) when the project is complex enough that an area needs a named group. Each with a README.
 
 ```
-wiki/
-  README.md                        # front door → roots
-  capabilities/                    # Wiki > Capabilities
-    README.md                      # areas index
-    {area}/                        # Wiki > Capabilities > {Area}
-      README.md                    # features index
-      {feature}.md                 # Wiki > … > {Feature}  — leaf
-      {group}/                     # optional extra nesting
-        README.md
-        {feature}.md
-  catalog/                         # Wiki > Catalog  — list of functionalities
-    README.md                      # areas index
-    {area}/
-      README.md                    # YAML index
-      {feature}.yaml
-      {group}/
-        README.md
-        {feature}.yaml
-  mismatches/                      # optional — create when a disagreement exists
-    README.md
+{output}/                    # output folder
+  README.md                  # sitemap, baseline commit
+  features/
+    README.md                # areas
+    .catalog/                # internal: code catalog (catalog-features)
+    {area}/                  # any depth, as in the catalog
+      README.md              # subareas and features
+      {feature}.md           # feature page
+      {subarea}/             # as in the catalog
+        README.md            # subareas and features
+        {feature}.md         # feature page
+  mismatches/                # code vs claims in the repo
+    README.md                # index
+    {mismatch}.md            # one behavior, every source that disagrees
 ```
 
-Create `mismatches/` when code disagrees with comments, infra, docs, issues etc.
+## Feature page
 
-## Rules
+- Breadcrumb that matches folders.
+- Feature description.
+- `## Behaviors`: [behaviors.md](behaviors.md).
 
-| Rule | Do |
-| --- | --- |
-| Default | `capabilities/{area}/{feature}.md` |
-| Extra depth | New group folder when the area (or group) is too crowded or a cluster needs a name. Any depth. |
-| Split | New sibling `{feature}.md`, a new group folder, or a new `{area}/`. |
-| Share | One page owns a shared rule; others link. Same behavior, two entries → one page. |
-| Growth | New behavior → new leaf + catalog entry + one new index line. Do not thicken an existing leaf into a mega-page. |
-| Overview first | Indexes exist before any leaf is written. |
+## Catalog feature YAML
 
-## Formatting
+- No key (cause does not exist in code).
+- `links` become `code` paths.
 
-Every page: `# Title`, then a breadcrumb that matches folders, then the body. Omit empty sections. Relative links only.
+```yaml
+# features/.catalog/checkout/pay-with-saved-card.yaml
+title: Pay with saved card      # catalog-feature
+code:                           # implementation files
+  - src/api/cards.ts
+tests:                          # tests that cover the feature
+  - test/checkout/cards.spec.ts
+```
 
-**Index** (any `README.md`): title + breadcrumb + a bullet list. No Requirement or Acceptance.
+## Mismatches
 
-| File | Body |
-| --- | --- |
-| `wiki/README.md` | Roots (`capabilities/`, `catalog/`, `changes/` / `mismatches/` (if present)) |
-| `capabilities/README.md` | Every area: link + purpose (markdown indexes only — not catalog YAML) |
-| `capabilities/{area}/README.md` | Every child feature (or group): link + purpose |
-| Extra group `README.md` | Every child feature (or deeper group): link + purpose |
-| `catalog/README.md` | Every area: link to that area’s catalog README |
-| `catalog/{area}/README.md` | Every child YAML: link + purpose (YAML indexes only — not feature pages) |
+`mismatches/README.md` missing → create it: `# Mismatches`, breadcrumb. Write the list of mismatches, grouped by kind (not implemented, differs, unwired/not used, etc.), highest impact first: page link + impact level.
 
-**Leaf** (`{feature}.md`): headings in this order only — Requirement, Acceptance. After the breadcrumb, a relative link to the paired catalog YAML. Intended-but-unwired behavior is not a feature heading — it goes in `mismatches/` only. Code and tracker references live in catalog YAML (`sources`, `tests`, `issues`), never on the feature page.
+### Mismatch page
 
-## Catalog YAML
+A reader learns what disagrees from the first lines, without opening the sources.
 
-```yaml
-wiki_path: capabilities/{area}/{feature}.md
-entry:
-  - POST /api/v1/orders
-  - UI /checkout
-  - Job SettlePayments
-sources:
-  - path/to/code
-tests:
-  - TestOrSpecFile
-issues:                    # optional; omit the key when none
-  - key: PROJ-123
-    url: https://example.com/browse/PROJ-123
-behaviors:
-  - One as-implemented fact (observable outcome).
-```
+File name: follow existing file name pattern or kebab-case of the title by default.
+
+- `# Title`: the behavior in question, as the user meets it.
+- `Feature:` the feature area › title, linked to its feature page.
+- `## Difference`: first a one-sentence summary of how they differ, then one bullet for the code, first, then one per claim; claims that agree grouped on one bullet. Each bullet: the source, then its behavior. Write each side so it is clear alone: the condition, then what the user gets.
+- `## Impact`: level first: **High** (users blocked, data or money wrong), **Medium** (a workaround exists), **Low** (wording, cosmetic). Then who meets it, when, and what they see or cannot do.
+- `## Solution`: suggested fix: change the code, or correct the claim.
+- `## Sources`: evidence, one row per source; Code row always, first. Code, Comment, Docstring, README, Developer docs, API spec, Config, Infra, Test, etc.
+- Other info required to explain the mismatch.
+
+#### Example
 
-`entry` is whatever a human would use to *find* the behavior. Catalog is **implicit** current state. One YAML per feature. If the feature sits in extra folders, the YAML uses the same folders.
+```markdown
+# Upload retries after a network error
 
-`wiki_path` is the pointer from catalog to the feature page. `sources` is the implementation (and product docs that describe it). `issues` is optional tracker links (tasks, issues, stories). `url` is required on each item; `key` when the tracker has a display key. Ask before adding. Omit `issues` when the user declined or nothing matched.
+Feature: [Reports › Upload results](../features/reports/upload-results.md)
 
-Repo paths (implementation, tests, docs) and tracker links are written only in catalog YAML.
+## Difference
 
-## Mismatch page
+The code retries a failed upload 3 times; the docstring and developer docs say 5.
 
-Create `mismatches/` when code disagrees with comments, infra, docs, issues/tasks. Index: `mismatches/README.md`.
+- **Code:** A failed upload is retried 3 times, then the run shows "Upload failed".
+- **Docstring, developer docs:** A failed upload is retried 5 times.
 
-Every mismatch must link every source that justifies it (omit none that exist):
+## Impact
+
+Low. On a flaky network, "Upload failed" shows after 3 attempts, sooner than a developer reading the docs expects.
+
+## Solution
+
+Correct the docstring and developer docs: 3 retries.
+
+## Sources
+
+| Source         | Says                         | Link                        | Updated    |
+| -------------- | ---------------------------- | --------------------------- | ---------- |
+| Code (actual)  | Retries 3 times, then fails  | `src/upload/client.ts:40-52` | 2026-09-02 |
+| Docstring      | "Retries up to 5 times"      | `src/upload/client.ts:31`    | 2026-03-11 |
+| Developer docs | "5 retries before giving up" | `docs/upload.md:18`          | 2026-03-11 |
+```
 
-| Link | What to point at |
-| --- | --- |
-| Implemented | Always — current behavior based on code |
-| Intended | Always — the non-wiki source that disagrees with those files (comment, doc, infra, issue, unused config, or stub) |
+- `Link`: repo file: `path:lines`; outside the repo: URL, with the heading when the page is long.
+- `Updated`: repo file: date the cited line last changed (`git blame --date=short -L {line},+1 -- {path}`), doc section without a line: the section's last change; URL: the page's "last updated" date, else empty.

package/dist/src/mcp-extension.js

@@ -1,9 +0,0 @@
-import { mcpConfig, seedMetadataCache, vendorBundle } from "./mcp.js";
-/** The MCP adapter, configured from the environment, as a pi extension. */
-export default async function mcpExtension(pi) {
-    const config = mcpConfig();
-    await seedMetadataCache(config);
-    const { createMcpAdapter } = (await import(vendorBundle()));
-    await createMcpAdapter({ config })(pi);
-}
-//# sourceMappingURL=mcp-extension.js.map

package/dist/src/mcp-extension.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"mcp-extension.js","sourceRoot":"","sources":["../../src/mcp-extension.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEtE,2EAA2E;AAC3E,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,YAAY,CAAC,EAAW;IACpD,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAEhC,MAAM,EAAE,gBAAgB,EAAE,GAAG,CAAC,MAAM,MAAM,CAAC,YAAY,EAAE,CAAC,CAEzD,CAAC;IACF,MAAM,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;AACzC,CAAC"}