feat: add docs for Cloud Capture

[gsavage]

The Kosli Capture Managed service is still in the design phase, so the content here is marked as "BETA". This PR adds documentation on the overall service, how to get started with it, and how it is secured.

The purpose of making the documentation available, merged, before the build is complete is to allow our customers to provide feedback on the overall design and security of the solution.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
kosli	🟢 Ready	View Preview	Sep 24, 2026, 10:21 AM

[claude]

Claude finished @gsavage's task in 3m 8s —— View job

---

Doc review — Cloud Capture pages

• Read changed files at branch HEAD (d9f4f20)
• Check config/navigation.json entries, image paths, redirects
• Cross-file consistency (rename sweep, AWS/GCP parity, links and anchors)
• Post findings

The Kosli Capture → Cloud Capture rename in the latest push is clean in prose across all five content files — I found no stale "Kosli Capture" in any sentence. Structural checks pass: all three new pages are in config/navigation.json (core rule 2), both images resolve (images/administration/cloud-capture-overview.png, cloud-capture-4-steps.png) and now carry alt text, every internal link is root-relative, and no redirect is needed since these paths never existed on main. I could not run mint broken-links or scripts/audit_navigation.py in this environment, so the navigation check above is by inspection.

Six findings, posted inline, most significant first:

#	File	Finding
1	administration/cloud_capture/getting_started.md:20	Shared <Steps> block above the tabs says "Create an IAM role", contradicting the GCP tab's service-account/workload-identity path
2	administration/cloud_capture/security.md:339	"the AWS account in which the Cloud Capture is running" — stranded article left by the rename
3	administration/cloud_capture/security.md:29	Rename reached prose and code comments but not identifiers (KosliCaptureAccessRole, kosli-capture, kosliCapture, kosli_capture_*) — confirm these match what's published
4	getting_started/environments.md:58	"Kosli can also report these snapshots for you" sits right after the full list of environment types; Capture covers a subset
5	administration/cloud_capture/getting_started.md:64	Deployment-command link points at the bare security page; #deploying-with-infrastructure-manager exists
6	administration/managing_environments/overview.md:67	Non-Terraform heading under a Terraform-only section — the placement you flagged yourself

Two smaller things not worth their own inline comments:

• getting_started.md still repeats ### Prepare your environment, ### Enable Cloud Capture and ### Excluding resources once per tab. Demoting them to ### fixed the worst of it, and the #excluding-resources anchor linked from overview.md:44 does resolve to the AWS heading, so nothing is broken — but the right-hand table of contents lists all three twice with no way to tell AWS from GCP.
• overview.md is framed entirely around AWS (lines 42–54: "within your AWS accounts", ## Multiple AWS accounts, "all of your AWS ECS clusters") while security.md and getting_started.md both carry a GCP tab. That is defensible while GCP is marked coming soon. The one GCP fact I would still pull up to the overview is the hard prerequisite at security.md:144-148 — a GKE cluster whose control plane has a private endpoint only cannot be snapshotted. That is a "can Capture cover my estate at all" question, and it is currently reachable only by opening a tab on the security page.

Given the PR's stated purpose — merging early so customers can review the design and security model — the structure holds up well for that. Findings 1 and 3 are the two a customer doing that review is most likely to trip over.
· branch kosli-capture-docs

[claude]

Improvement — this <Steps> block sits above the <Tabs>, so it is the summary for both clouds, but "Create an IAM role" is AWS-only and is contradicted by line 58 in the GCP tab: there the reader creates a service account and a workload identity pool, and there is no role for them to create in their project.

A GCP reader's very first instruction on this page is therefore for a resource that does not exist on their platform.

Suggested change

	<Step title="Prepare your environment">
	Create an IAM role in your cloud accounts specifically for Kosli Capture.
	</Step>
	<Step>
	Grant Kosli Capture read-only access to your cloud accounts — an IAM role on AWS, or a service account reached through workload identity federation on GCP.
	</Step>

Fix this →

[claude]

Improvement — this <Steps> block sits above the <Tabs>, so it is the summary for both clouds, but "Create an IAM role" is AWS-only and is contradicted by line 58 in the GCP tab: there the reader creates a service account and a workload identity pool, and there is no role for them to create in their project.

A GCP reader's very first instruction on this page is therefore for a resource that does not exist on their platform.

Suggested change

	Create an IAM role in your cloud accounts specifically for Cloud Capture.
	Grant Cloud Capture read-only access to your cloud accounts — an IAM role on AWS, or a service account reached through workload identity federation on GCP.

Fix this →

[claude]

Improvement — "the AWS account in which the Cloud Capture is running" is a grammar slip introduced by the Kosli Capture → Cloud Capture rename: the old text read "in which the Kosli Capture Managed service is running", and dropping "Managed service" left a stranded article. Vale won't catch it — every word is real.

Suggested change

	The trust policy on the role in your account limits access to the AWS account in which the Cloud
	Capture is running. The ExternalId acts as a shared secret between Kosli and you, so that only
	Cloud Capture is permitted to assume the role.
	The trust policy on the role in your account limits access to the AWS account in which Cloud
	Capture is running. The ExternalId acts as a shared secret between Kosli and you, so that only
	Cloud Capture is permitted to assume the role.

Fix this →

[claude]

Improvement — the rename swept the prose and the code comments but not the identifiers. This page still publishes KosliCaptureAccessRole here, and on the GCP side workload_identity_pool_id = "kosli-capture" (197), account_id = "kosli-capture" (235), role_id = "kosliCapture" (284), the outputs kosli_capture_provider / kosli_capture_service_account (252, 257) and deployments/kosli-capture (316).

That may well be correct — renaming a live CloudFormation logical id forces resource replacement, so keeping it is a defensible choice. But these are values a customer copies verbatim, and the page gives no signal either way, so it reads as a half-finished sweep. Worth one sentence confirming the published template and Terraform still use these names, or aligning them if they don't.

Fix this →

[claude]

Improvement — this sentence lands immediately after the list of supported environment types (K8S, ECS, S3, Lambda, Azure Web Apps, Cloud Run, …), and "these snapshots" reads as all of the above. Cloud Capture covers ECS and Lambda today; GCP is marked "coming soon" on both Cloud Capture pages, and nothing there mentions S3, Azure or Cloud Run.

You noted earlier that keeping the supported-resource list vague on the Capture page is deliberate, which is fair — but that makes this inbound sentence the one place worth qualifying, because it is the only one that sits next to a concrete list. A qualifier costs nothing and commits you to nothing.

Suggested change

You can report environment snapshots manually using the `kosli snapshot [...]` commands for testing. For production use, however, you would configure the reporting to happen automatically on regular intervals, e.g. via a cron job or scheduled CI job, or on certain events. Kosli can also report these snapshots for you, using [Cloud Capture](/administration/cloud_capture/overview).

You can report environment snapshots manually using the `kosli snapshot [...]` commands for testing. For production use, however, you would configure the reporting to happen automatically on regular intervals, e.g. via a cron job or scheduled CI job, or on certain events. For some environment types, Kosli can also report these snapshots for you, using [Cloud Capture](/administration/cloud_capture/overview).

Fix this →

[claude]

Suggestion — both links in this tab (line 62 and here) point at the bare page URL, but they send the reader to two different places: line 62 wants the trust model and permission list, and this one wants the deployment command. security.md:308 already has a ### Deploying with Infrastructure Manager heading, so the second link can land on it directly rather than dropping the reader at the top of a 350-line page they then have to scroll.

Suggested change

GCP has no equivalent of the CloudFormation "phone-home" feature, so the Terraform configuration emits the two values Kosli needs — the workload identity provider and the service account email — as outputs. Share them with Kosli once the deployment completes; you can read them at any time with `gcloud infra-manager deployments describe`. See [Cloud Capture Security](/administration/cloud_capture/security) for the deployment command.

GCP has no equivalent of the CloudFormation "phone-home" feature, so the Terraform configuration emits the two values Kosli needs — the workload identity provider and the service account email — as outputs. Share them with Kosli once the deployment completes; you can read them at any time with `gcloud infra-manager deployments describe`. See [Cloud Capture Security](/administration/cloud_capture/security#deploying-with-infrastructure-manager) for the deployment command.

Fix this →

[claude]

Suggestion — you agreed earlier that this heading may be in the wrong place, and it still is. It sits under ## Managing physical environments on a page whose lede states "This page covers managing environments via Terraform" (line 13), and every other ### in that section is a Terraform operation (Create a physical environment, Import an existing physical environment). A non-Terraform cross-link as a sibling reads as an orphan.

The lightest fix that keeps the pointer: fold it into the existing ### Import an existing physical environment section as a closing sentence — Cloud Capture's output is importable, which is the Terraform-relevant fact and the thing this page's reader would want to know — rather than giving it a heading of its own.

Fix this →