Sync kane cli docs from testmuCom (MDX format)

docs.json

@@ -96,6 +96,7 @@
                 "pages": [
                   "docs/kane-cli-assurance",
                   "docs/kane-cli-assurance-context",
+                  "docs/kane-cli-assurance-sources",
                   "docs/kane-cli-assurance-design",
                   "docs/kane-cli-assurance-coverage",
                   "docs/kane-cli-assurance-maintain",

docs/kane-cli-assurance-context.mdx

@@ -28,7 +28,9 @@ kane-cli context list                           # see what you have
 kane-cli context ingest <src...> [--as <id>]
 ```
 
-Snapshots one or more files into `.context/` (the store is created on first use). Each source gets a stable id — by default the filename slug (`prd-online-store.md` → `prd-online-store`), or pass `--as <id>` to name it yourself.
+Snapshots one or more sources into `.context/` (the store is created on first use). A source is a file path or a remote URL — a Jira issue, a Confluence page, a Linear issue or document, or a public web page. See [Requirement Sources](/docs/kane-cli-assurance-sources/) for every accepted type.
+
+Each source gets a stable id — by default the filename slug (`prd-online-store.md` → `prd-online-store`), or the issue key for a ticket (`ENG-42` → `eng-42`). Pass `--as <id>` to name it yourself.
 
 Ingest is deterministic about identity:
 
@@ -44,7 +46,25 @@ $ kane-cli context ingest ./prd-online-store.md
 created  prd-online-store  source sha256:0661…  blob sha256:3db8…
 ```
 
-Accepted media: text (`.txt`) and markdown (`.md`, `.markdown`) up to 2 MB — cited verbatim by line; PNG/JPEG/WebP images up to 5 MB — cited whole-image. Anything else is rejected with `UNSUPPORTED_MEDIA`; oversized files with `FILE_TOO_LARGE`.
+### Accepted sources
+
+Files: text and structured text up to 2 MB, images up to 5 MB, PDF and Word documents up to 25 MB.
+
+Remote sources, passed as a URL and requiring the matching connection on your account:
+
+```bash
+kane-cli context ingest https://<your-site>/browse/PROJ-123              # Jira issue
+kane-cli context ingest https://<site>/wiki/spaces/<KEY>/pages/<id>/…    # Confluence page
+kane-cli context ingest https://linear.app/<workspace>/issue/KEY-123     # Linear issue
+kane-cli context ingest https://linear.app/<workspace>/document/<slug>   # Linear document
+kane-cli context ingest https://docs.example.com/guide                   # public web page
+```
+
+Anything else is rejected with `UNSUPPORTED_MEDIA`, and oversized files with `FILE_TOO_LARGE`. Every source type, with its size cap, citation granularity, identity rules and refusal codes, is documented in [Requirement Sources](/docs/kane-cli-assurance-sources/).
+
+<Note>
+A Jira `ENG-42` and a Linear `ENG-42` both mint the id `eng-42`. A URL whose id is already backed by a different kind of source refuses and offers a recovery rather than replacing it silently.
+</Note>
 
 When the new bytes are a **changed version of a source you already extracted from**, prefer [`kane-cli maintain reconcile`](/docs/kane-cli-assurance-maintain/) over a bare re-ingest — it records the same head move *and* triages what the change means for your suite, in one step.
 
@@ -250,6 +270,7 @@ Headless extraction (`--mode agent|ci|override`), the NDJSON event stream, exit
 
 ## Next steps
 
+- [Requirement sources](/docs/kane-cli-assurance-sources/) — every accepted file type and remote URL.
 - [Designing tests](/docs/kane-cli-assurance-design/) — turn a trusted use-case into ACs, scenarios, and runnable tests.
 - [Maintaining the suite](/docs/kane-cli-assurance-maintain/) — what to do when a source changes.
 - [Automation](/docs/kane-cli-assurance-automation/) — the headless contract.

docs/kane-cli-assurance-maintain.mdx

@@ -30,7 +30,7 @@ Reconcile is the on-change front door: a requirement document changed — what s
 
 It takes **two explicit inputs** — reconcile never guesses which source a file belongs to:
 
-- `--from <file>` — the **new** version of the document (a file path).
+- `--from <file|url>` — the **new** version of the document: a file path, or a remote source URL — a Jira issue, a Confluence page, a Linear issue or document, or a public web page. These are the same URLs [`context ingest`](/docs/kane-cli-assurance-sources/) takes. See [Remote sources](#remote-sources) below.
 - `--source-id <id>` — the **existing** source this file succeeds; its head moves. Find ids with `kane-cli context list --type source`.
 
 Both are required on a fresh run. `--apply <path>` alone is enough to continue a stored plan — the plan remembers its source.
@@ -87,6 +87,30 @@ After the last card the composer wakes: type `<uc-ref> <what to change>` to rout
 
 Walk the plan later with `--apply <path>` — or bare `--apply`, which picks the latest plan behind an approval prompt (headless modes accept it silently). `--apply --from <file> --source-id <id>` recomputes live instead. `--plan` and `--apply` together is a usage error (exit `2`). A repeated `--plan` re-renders the stored plan; an unchanged source is a truthful no-op (`nothing to reconcile`).
 
+<a id="remote-sources" />
+### Remote sources — `--from <url>`
+
+`--from` also accepts a remote source URL: a Jira issue, a Confluence page, a Linear issue or document, or a public web page. These are the same URLs [`context ingest`](/docs/kane-cli-assurance-sources/) takes.
+
+Remote sources ride the same flow as files. Reconcile fetches the latest content through the provider, the head moves if anything you would cite changed, and everything downstream — the cards, `--plan` and `--apply` — is identical.
+
+```bash
+kane-cli maintain reconcile --from https://<your-site>/browse/PROJ-123 --plan
+kane-cli maintain reconcile --from https://<site>/wiki/spaces/<KEY>/pages/<id>/…
+kane-cli maintain reconcile --from https://linear.app/<workspace>/issue/ENG-42
+kane-cli maintain reconcile --from https://docs.example.com/guide
+```
+
+Three rules are specific to remote sources:
+
+- **The id comes from the URL.** `proj-123` or `eng-42` for an issue, `page-<id>` for a Confluence page, `doc-<id>` for a Linear document, and a slug plus a short hash for a web page. That makes `--source-id` optional. Passing one that contradicts the URL's own identity refuses, because reconcile never adopts a URL under a different id. A source you ingested under a custom id with `context ingest --as` is maintained by re-running that ingest with the same `--as`.
+- **Kind continuity, both ways.** A URL cannot version a file-backed source that happens to share its id, and a file cannot version a remote source. Each refuses and names the correct `--from`. The same check runs when a stored plan replays, so a stale plan can never overwrite a source whose backing changed hands.
+- **Stored plans remember the URL** and recompute by re-fetching it, the same way a file plan re-reads its file.
+
+<Note>
+After an upgrade, the first reconcile of a Jira issue ingested on an older release may report a head move that is not a content edit. That is the source's one-time re-version, not a change to review.
+</Note>
+
 <a id="running-again" />
 ### Running again — reconcile converges
 
@@ -145,6 +169,7 @@ Evolve re-designs the **parent use-case** of whatever you point it at — a test
 
 ## Next steps
 
+- [Requirement sources](/docs/kane-cli-assurance-sources/) — every file type and remote URL reconcile accepts.
 - [Coverage](/docs/kane-cli-assurance-coverage/) — `cover gaps --stage design` is the standing worklist between reconciles.
 - [Designing tests](/docs/kane-cli-assurance-design/) — what an approved ADD row actually runs.
 - [Automation](/docs/kane-cli-assurance-automation/) — reconcile in CI, and its NDJSON stream.

docs/kane-cli-assurance-sources.mdx

@@ -0,0 +1,147 @@
+---
+title: "Requirement Sources"
+sidebarTitle: "Requirement Sources"
+description: "Every source type kane-cli can ingest as a requirement: text, PDF, Word documents, images, and remote sources by URL including Jira issues, Confluence pages, Linear issues and documents, and public web pages."
+keywords: ['kane cli sources', 'ingest jira', 'ingest confluence', 'ingest linear', 'requirement sources', 'context ingest', 'kaneai', 'testmu ai']
+"og:description": "Every source type kane-cli can ingest as a requirement — files, and remote sources by URL including Jira, Confluence, Linear and web pages."
+---
+
+import AgentSkillCallout from "/snippets/AgentSkillCallout.mdx";
+
+---
+
+<AgentSkillCallout />
+
+A requirement source is any document kane-cli snapshots into the [context graph](/docs/kane-cli-assurance-context/) so use-cases can be extracted from it and cited back to it. Sources are ingested with `kane-cli context ingest`, and the same URLs are accepted by [`maintain reconcile --from`](/docs/kane-cli-assurance-maintain/) when the source later changes.
+
+Only allowlisted media is accepted. Anything else is rejected with `UNSUPPORTED_MEDIA`, and each type has its own size cap, beyond which the ingest refuses with `FILE_TOO_LARGE`.
+
+## Supported sources at a glance
+
+| Source | How you pass it | Size cap | Citation granularity |
+|---|---|---|---|
+| Text and structured text | file path | 2 MB | per line |
+| Images | file path | 5 MB | whole image |
+| PDF | file path | 25 MB | per line, page-marked |
+| Word (`.docx`) | file path | 25 MB | per line |
+| Jira issue | issue URL | not stated | per line |
+| Confluence page | page URL | not stated | per line |
+| Linear issue | issue URL | not stated | per line |
+| Linear document | document URL | not stated | per line |
+| Public web page | page URL | not stated | per line |
+
+## Files
+
+### Text and structured text
+
+`.txt`, `.md` and `.markdown`, plus the structured-text family `.json`, `.yaml` and `.yml`, `.toml`, `.xml`, and `.log`. Cited verbatim by line, up to 2 MB.
+
+Structured files are ingested as-is, so a malformed JSON file is still citable evidence. Files must be valid UTF-8, otherwise the ingest refuses with `ENCODING_UNSUPPORTED`. A file with very long lines, for example minified JSON, ingests with a warning because line anchors lose granularity. Pretty-print it first if you want useful citations.
+
+### Images
+
+PNG, JPEG and WebP, up to 5 MB. An image is cited as a whole image, because there is no text to quote.
+
+### PDF
+
+Up to 25 MB. The document's text becomes the citable text, marked by page, and embedded images become citable parts of the same source.
+
+PDFs need selectable text. A scanned document refuses with `PDF_NO_TEXT_LAYER` and a password-protected one with `PDF_ENCRYPTED`. Every refusal names its remedy, such as splitting a very large document or re-saving an encrypted one.
+
+### Word documents
+
+`.docx` up to 25 MB, converted to a plain-text projection covering the body, headers and footers, footnotes, and tables, with tracked changes shown as the final view. Embedded images become citable parts.
+
+Anything not extracted leaves an explicit marker, so nothing vanishes silently. Password-protected files and legacy binary `.doc` are refused with save-as guidance.
+
+## Remote sources
+
+Remote sources are passed as a URL instead of a file path. Each requires the matching connection on your account, set up in the [Integrations screen](https://integrations.lambdatest.com). When a connection is missing or expired the ingest refuses up front and points you there.
+
+### Jira issues
+
+```bash
+kane-cli context ingest https://<your-site>/browse/PROJ-123
+```
+
+Ingested: the summary, the description, custom fields, the attachment inventory with image attachments as citable parts, and all comments with author, timestamp and body, every line citable.
+
+Comments are part of the issue's identity. If they cannot be read, the whole ingest refuses rather than recording the issue without them.
+
+Re-running the URL is `unchanged` or `versioned`, exactly like a re-ingested file. The default source id is the lowercased issue key, and `--as` overrides it.
+
+<Note>
+The project must be one of the integration's selected projects. An issue outside that set refuses and names the Integrations screen so you can add the project.
+</Note>
+
+### Confluence pages
+
+```bash
+kane-cli context ingest https://<site>/wiki/spaces/<KEY>/pages/<id>/...
+```
+
+The same Atlassian connection serves Jira and Confluence, but it needs Confluence access. A Jira-only connection refuses up front with reconnect guidance.
+
+Ingested: the title, space, labels, the page body with every line citable, and the attachment inventory with image attachments as citable parts.
+
+Re-ingesting reads the latest page version, and identity follows content. An edit that changes nothing you would cite, or a bare version bump, is `unchanged`. A body change is `versioned`, with staleness flowing to items extracted from the old snapshot. The default source id is `page-<id>`.
+
+Short links such as `/wiki/x/...` are not supported. Open the page and use its full URL.
+
+### Linear issues
+
+```bash
+kane-cli context ingest https://linear.app/<workspace>/issue/KEY-123
+```
+
+Slug, query and `#comment` variants of the same issue all converge on one source.
+
+Ingested: the title, the description with every line citable, workflow fields covering status, priority, project and labels, all comments including threaded replies, and images both inline and attached as citable parts. Attachment links to other apps are listed, never fetched.
+
+As with Jira, comments are part of the issue's identity, so a failed or partial comments read refuses the whole ingest.
+
+Identity follows the issue itself. Renaming a team key continues the same source as a `versioned` update, while a recycled key, meaning the same key now pointing at a different issue, refuses with a retire or `--as` recovery path. The default source id is the lowercased key, for example `eng-42`, and `--as` overrides it.
+
+### Linear documents
+
+```bash
+kane-cli context ingest https://linear.app/<workspace>/document/<slug>
+```
+
+The slug must end in the document's 12-hex id. The connection needs document access, and the refusal carries a resync hint otherwise.
+
+Ingested: the document body with every line citable, plus its inline images. The default id is `doc-<id>`, and `--as` overrides it.
+
+Workspace pages, meaning project, team or view URLs, are not ingestable and refuse loudly. Ingest their issues or documents individually.
+
+### Public web pages
+
+```bash
+kane-cli context ingest https://docs.example.com/guide
+```
+
+Any public page URL that is not a Jira issue, a Confluence page, or a Linear issue or document. The page is fetched and converted to text by the service, the CLI never fetches pages itself, with every line citable.
+
+The default id is a slug of the URL plus a short hash, so the same URL always converges on the same source. `--as` adopts a custom id, and re-ingesting a different URL under an adopted id asks first on a terminal. Headless it refuses, so keep separate pages under separate ids.
+
+Re-ingesting an unchanged page is `unchanged`. A content change is `versioned`, with staleness flowing to items extracted from the old snapshot. Title, redirect, status and timestamp changes never move the head.
+
+A web source is always the live page. There is no point-in-time read. Inaccessible pages, whether not found, behind a login or paywall, bot-blocked, non-HTML, too large or timing out, refuse with the reason in plain language. Private and internal addresses are refused.
+
+## Remote ids share one space
+
+A Jira `ENG-42` and a Linear `ENG-42` both mint the source id `eng-42`. A URL whose id is already backed by a different kind of source refuses and offers a recovery, either retiring the existing source or adopting the new one under `--as`. It is never a silent replace.
+
+<Warning>
+Linear pages ingested as **web** sources before 0.8.6 remain separate sources. Retire them, or keep both, but be aware they will not converge with a natively ingested Linear source.
+</Warning>
+
+## Keeping a source current
+
+When a source document changes, prefer [`kane-cli maintain reconcile`](/docs/kane-cli-assurance-maintain/) over a bare re-ingest. Reconcile records the same head move and triages what the change means for your suite, in one step. It accepts the same remote URLs listed here.
+
+## Next steps
+
+- [Building the context graph](/docs/kane-cli-assurance-context/) — ingest, extract, review.
+- [Maintaining the suite](/docs/kane-cli-assurance-maintain/) — what to do when a source changes.
+- [Designing tests](/docs/kane-cli-assurance-design/) — turn a trusted use-case into runnable tests.