docs: add Kosli Capture Managed Service page

[mintlify]

Adds a new "Kosli Capture Managed Service" page to the Getting started section, based on a customer-facing overview drafted by Graham.

• New page: getting_started/kosli_capture.md (sidebar label: "Kosli Capture")
• Content adapted to docs style: second-person voice, sentence-case headings, setup steps in a Steps component
• Added to the Getting started group in navigation, after Environments

---

Generated by Mintlify Agent.

Requested by: graham@kosli.com via Slack
Mintlify session: slack_1782915660.508229_D0AM66349C1

[mintlify]

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

Project	Status	Preview	Updated
kosli	🟢 Ready	View Preview	Sep 16, 2026, 7:29 AM

[claude]

Claude finished @gsavage's task in 2m 41s —— View job

---

Doc review

Seven findings, posted inline. Two things from earlier rounds are resolved at this head and are not repeated: all three new pages are now in config/navigation.json, and the relative ./kosli_capture_security link is gone — every internal link in the folder is root-relative.

Critical

Where	Finding
kosli_capture/getting_started.md:12	The opening sentence tells the reader to "provide configuration details for how your tags should map to environments", but the page's own procedure is an IAM role plus a UI toggle. This is the configuration document 0a1e3f9 removed.

Improvements

Where	Finding
kosli_capture/security.md:14	GCP and Azure are claimed only here; every mechanism on all three pages is AWS-only. Also, the "publicly accessible" CloudFormation template is named nine times across the folder and never linked.
kosli_capture/overview.md:24–30	The security bullets still say "A's account with A's ExternalId" — "A" is an undefined referent carried over from an internal design doc.
kosli_capture/overview.md:38–42	"All supported resources" is defined nowhere since Current status was dropped in 7afa53c; "the configuration created during the initial setup" refers to a configuration that no longer exists.
managing_environments/overview.md:69	"according to rules you define" no longer matches the linked page — there are no rules to define.
kosli_capture/overview.md:48–54	Trust-policy prose here duplicates the YAML on security.md; worth deciding which page owns it now that they are split.
kosli_capture/security.md:102	Closing fence has four backticks; neither block declares a language; the S3 removal took away the comment explaining why the surviving explicit deny exists.

Two smaller things, not worth their own inline comments

• overview.md sets sidebarTitle: "Kosli Capture" inside a group also called "Kosli Capture", so the sidebar renders Kosli Capture ▸ Kosli Capture. The managing_environments and managing_custom_attestation_types groups both label their overview.md as "Overview".
• getting_started.md:20 calls it "a shared secret, which Kosli provides to you"; line 31 calls the same thing "an external Id". Unify on "external ID" (the form overview.md:52 and security.md:41 use), and say how you obtain it.

This review is advisory — nothing here blocks the merge, and I have not requested changes.
· branch mintlify/2dca75a3

[claude]

Improvement — this section still refers to an unnamed "customer A". Line 29 reads "Only that role is permitted to call AssumeRole into A's account with A's ExternalId." Nothing on the page defines "A" — it reads as a leftover from an internal design document where customers were labelled A and B. This is the one section a reader is most likely to forward to their own security team, and it contains an unresolvable pronoun.

Two more defects in the same block: line 27 has no closing full stop ("...scoped to one customer"), and line 33 is a comma splice ("...customer data, it is near-stateless...") whose second clause also doesn't parse ("with the only thing it keeps is your configuration data").

Suggested change

	The security of your cloud infrastructure is the primary driver behind the internal architecture of the Kosli Capture managed service. Kosli Capture runs as a shared, autoscaled service, but each job runs under a role that is scoped to one customer
	* A Kosli Capture worker picks up a job for your organization and assumes a Kosli-side role that exists only for your organization. Only that role is permitted to call AssumeRole into A's account with A's ExternalId.
	* When the job finishes, those credentials are discarded. A worker holding credentials for your cloud account has no path to anyone else's account.
	* The trust policy's ExternalId lives in Parameter Store and is readable only by the Kosli-side role for your organization. The shared task role cannot read any customer's ExternalId. Separation is enforced by IAM, not by application code.
	Kosli Catpure does not hold any customer data, it is near-stateless with the only thing it keeps is your configuration data. Snapshots taken by Kosli Catpure are immediately sent to Kosli through the same ingest path as your existing pipelines.
	The security of your cloud infrastructure is the primary driver behind the internal architecture of the Kosli Capture managed service. Kosli Capture runs as a shared, autoscaled service, but each job runs under a role that is scoped to a single customer.
	* A Kosli Capture worker picks up a job for your organization and assumes a Kosli-side role that exists only for your organization. Only that role is permitted to call `AssumeRole` into your account with your external ID.
	* When the job finishes, those credentials are discarded. A worker holding credentials for your cloud account has no path to any other account.
	* The trust policy's external ID lives in Parameter Store and is readable only by the Kosli-side role for your organization. The shared task role cannot read any customer's external ID. Separation is enforced by IAM, not by application code.
	Kosli Capture holds no customer data. It is near-stateless, keeping only your configuration. Snapshots taken by Kosli Capture are immediately sent to Kosli through the same ingest path as your existing pipelines.

(The suggestion also unifies on "external ID", the form used on lines 71–73 and on the security page.)

[claude]

Improvement — GCP and Azure are claimed only here, and the "publicly accessible" template still has no URL.

Two problems in one sentence:

1. GCP/Azure. This says Kosli Capture "uses the public AWS, GCP and Azure APIs", but every mechanism described across both pages is AWS-only: an IAM role, a CloudFormation template, and ECS/Lambda policy statements. kosli_capture/overview.md:57 and :65 talk only about AWS accounts and regions. The Current status section that used to scope this ("Support for … other cloud providers is in active development") was dropped in 7afa53c, so this line is now the only provider-scope statement on either page — and it over-claims. A reader on GCP or Azure is told their provider's API is used and then given no way to grant access.
2. The template URL. "The template is publicly accessible and can be used directly within an aws cloudformation create-stack call" is the most actionable sentence on the page, but the template is named five times across the two pages and never once linked. A reader who wants to review the permissions before contacting Customer Success has nowhere to go. If the URL is public, link it and show the create-stack invocation. If it is not public yet, say "Kosli provides the template during onboarding" so the reader stops looking.

Suggested change

The Kosli Capture managed service uses the public AWS, GCP and Azure APIs to extract information about your cloud environments. In order to do this, you need to provide Kosli with an IAM role that allows access to these APIs. The role is created and owned by you. Kosli publishes a CloudFormation template, for use in AWS, showing the permissions needed. The template is publicly accessible and can be used directly within an `aws cloudformation create-stack` call.

The Kosli Capture managed service uses the public AWS APIs to extract information about your cloud environments. To do this, you provide Kosli with an IAM role that allows access to these APIs. The role is created and owned by you. Kosli publishes a CloudFormation template showing the permissions needed, which you can use directly in an `aws cloudformation create-stack` call.

[claude]

Improvement — "all supported resources" is no longer defined anywhere on the site.

7afa53c removed the Current status section, which was the only statement of what Kosli Capture can snapshot, and b6dd574 then dropped the S3 statements from the policy on the security page. At this HEAD:

• line 57 says "all supported resources" without defining the set;
• line 61 uses ECS clusters and Lambdas only as incidental examples;
• the only real signal is the IAM policy on security.md (ECS + Lambda).

So a reader evaluating Kosli Capture has to reverse-engineer the supported resource types from an IAM policy on another page. One sentence naming them restores what the removed section provided, and gives you an obvious place to update when S3 or EKS lands.

Separately, environment auto-creation is claimed twice — line 57 ("Kosli Capture will create physical environments for you") and again on line 61 ("Because Kosli Capture creates physical environments as needed, when your infrastructure changes, Kosli will keep up"), where it is restated as its own reason. Folding it into the evolution paragraph lands it once, in the place where it matters.

Suggested change

	Kosli Capture finds all supported resources within your AWS accounts, and examines the tags on those resources to determine which Kosli environment should hold the snapshots. Kosli Capture will create physical environments for you.
	Kosli Capture can filter out resources based on your tags.
	As your cloud environment evolves, such as the addition of new ECS clusters or the retirement of existing Lambdas, Kosli Capture automatically detects the changes. Because Kosli Capture creates physical environments as needed, when your infrastructure changes, Kosli will keep up. No changes to the configuration created during the initial setup are required.
	Kosli Capture currently snapshots ECS services and Lambda functions. It finds these resources within your AWS accounts and examines their tags to determine which Kosli environment should hold the snapshots.
	Kosli Capture can filter out resources based on your tags.
	As your cloud environment evolves, such as the addition of new ECS clusters or the retirement of existing Lambdas, Kosli Capture automatically detects the changes and creates any new physical environments needed. No changes to the configuration created during the initial setup are required.

[claude]

Improvement — the closing clause over-claims against the tag-driven model this page is built on.

"your application teams do not need to take any action in order to onboard their products and services into Kosli" contradicts lines 18, 23 and 57, which all say routing is driven by your tagging scheme. An untagged new service cannot be routed into an environment, so the action app teams do need to take is tagging their resources to the scheme. Stating that is more useful than claiming zero action — it is exactly the instruction a platform team needs to pass on, and it is the one thing that will generate support tickets if left unsaid.

Suggested change

Kosli Capture has been designed to operate with no on-going support from you. Once the initial security permissions have been created, Kosli capture will continue to operate in a headless mode. Monitoring, maintenance and rotation of API keys is all handed automatically. As your cloud infrastructure changes over time, Kosli capture will continue to find resources according to your tagging scheme without you needing to do anything; your application teams do not need to take any action in order to onboard their products and services into Kosli.

Kosli Capture has been designed to operate with no on-going support from you. Once the initial security permissions have been created, Kosli Capture will continue to operate in a headless mode. Monitoring, maintenance and rotation of API keys is all handled automatically. As your cloud infrastructure changes over time, Kosli Capture will continue to find resources according to your tagging scheme; as long as application teams tag their resources to that scheme, their products and services are onboarded into Kosli with no further action.

[claude]

Improvement — with the pages now split, this section and ## Security above duplicate the dedicated security page.

6e1d5c5 gave Kosli Capture its own folder with security.md as a sibling, but the overview still carries two sections on the same subject: ## Security (lines 25–33, the worker/role isolation model) and ## IAM permissions (this section, the trust policy and external ID). security.md covers the trust policy in full, including the actual AssumeRolePolicyDocument, so lines 71–73 are a prose restatement of a YAML block one click away — and the two will drift.

Worth deciding what each page owns. A reasonable split: the overview says what access is needed and why it is safe in two or three sentences, and the security page owns the mechanism. Right now the only link between them is buried at the end of line 69, and security.md has no link back — the pair is navigable only via the sidebar.

Two things on line 69 itself: "deep-diver" should be "deep dive", and there is a double space before "The".

Suggested change

	## IAM permissions
	For Kosli Capture to snapshot your environment, you must grant a set of read-only permissions. Kosli's CloudFormation template lists these. The permissions are typically "Describe" or "List" permissions. The [Kosli Capture Security](/administration/kosli_capture/security) page provides a deep-diver into the structure of the permissions needed.
	The IAM role created in your environment includes a trust policy that allows Kosli Capture to assume the role. The trust policy limits access to the AWS account in which Kosli Capture is running. Furthermore, the trust policy includes an external ID that acts as a shared secret between Kosli and you, so that only access from Kosli Capture is permitted.
	The external ID (shared secret) is securely stored with Kosli Capture. Kosli's internal IAM permissions ensure that the secret can only be accessed by the specific instance of Kosli Capture worker that is operating for you.
	For Kosli Capture to snapshot your environment, you must grant a set of read-only permissions. Kosli's CloudFormation template lists these, and they are typically "Describe" or "List" permissions.
	The IAM role you create includes a trust policy that allows only Kosli Capture to assume it, using an external ID that acts as a shared secret between you and Kosli. The [Kosli Capture security](/administration/kosli_capture/security) page is a deep dive into the role, the trust policy, and the full permission list.

[claude]

Suggestion — the S3 removal left this deny unexplained, and the closing fence has four backticks.

b6dd574 removed the S3BucketMetadataOnly allow and the NeverReadObjectData deny, and with them the comment that explained why explicit denies appear in an allow-list policy at all ("redundant given the allow-list above, but they are here so that a reviewer can verify the boundary…"). NeverDownloadFunctionCode is now the only deny in a policy of allows: its comment says what it blocks, but not why a deny is used rather than simply omitting the action. On a page whose purpose is passing someone else's security review, that rationale was the valuable part.

Also, line 100 closes with (four backticks). CommonMark still terminates the block so it renders, but it is a stray character on the last line of the page. And neither block on this page (lines 20 and 46) declares a language, so a page that is entirely YAML gets no syntax highlighting — worth changing both openers to ```yaml ````.

Suggested change

	# lambda:GetFunction returns a pre-signed URL to the deployment
	# package. That is source-code access, so it is denied outright.
	- Sid: NeverDownloadFunctionCode
	Effect: Deny
	Action:
	- lambda:GetFunction
	- lambda:GetLayerVersion
	Resource: "*"
	````
	# lambda:GetFunction returns a pre-signed URL to the deployment
	# package. That is source-code access, so it is denied outright.
	# The deny is belt-and-braces given the allow-list above, but it
	# is here so a reviewer can verify the boundary without reasoning
	# about IAM defaults, and so that any future widening of this
	# policy cannot accidentally grant code access.
	- Sid: NeverDownloadFunctionCode
	Effect: Deny
	Action:
	- lambda:GetFunction
	- lambda:GetLayerVersion
	Resource: "*"

[claude]

Suggestion — doubled word, and these two bullets are punctuated unlike every other list on the pages.

"to this this architecture" has a doubled "this". The bullets also start lowercase and terminate with ; / ., whereas the bulleted lists at lines 29–31 and on the security page are sentence-cased.

Suggested change

	There are several benefits to this this architecture:
	* the only infrastructure you need to manage is an IAM role; you do not need to install or execute any additional software in your cloud estate;
	* Kosli Capture leverages your existing tagging scheme, so as your infrastructure evolves, Kosli Capture will automatically discover the snapshots it needs to take.
	There are several benefits to this architecture:
	* The only infrastructure you need to manage is an IAM role — you do not need to install or run any additional software in your cloud estate.
	* Kosli Capture leverages your existing tagging scheme, so as your infrastructure evolves, Kosli Capture automatically discovers the snapshots it needs to take.

[claude]

Critical — administration/kosli_capture/getting_started.md is not listed here. The new group lists only overview and security, so the third new page is an orphan: it will not appear in the sidebar, and nothing else in the repo links to it (grep -rn "kosli_capture/getting_started" returns nothing). CLAUDE.md core rule 2 requires the nav entry, and pytest tests/ enforces navigation integrity — the Test live-docs scripts check should fail this PR as it stands.

Worth deciding placement rather than just appending it. getting_started.md is the only how-to of the three (it has the actual <Steps>, the CloudFormation deployment options, and the kosli.capture=false exclusion tag), so it is also the page a reader arriving from /getting_started/environments most needs. Ordering it first in the group reads better than after security.

Two smaller things while you are in here:

• overview.md sets sidebarTitle: "Kosli Capture" inside a group also called "Kosli Capture", so the sidebar renders Kosli Capture ▸ Kosli Capture. "Overview" matches the managing_environments / managing_custom_attestation_types groups, which both label their overview.md page as Overview.
• getting_started.md sets sidebarTitle: "Managed Service", which does not describe a setup page and reads oddly next to a sibling titled Security. "Getting started" or "Setup" would be clearer.

Suggested change

	"pages": [
	"administration/kosli_capture/overview",
	"administration/kosli_capture/security"
	]
	"pages": [
	"administration/kosli_capture/overview",
	"administration/kosli_capture/getting_started",
	"administration/kosli_capture/security"
	]

[claude]

Improvement — "three stages" is followed by two steps. The <Steps> block contains exactly two <Step> elements, and the page body below has exactly two matching ## sections ("Prepare your environment", "Enable Kosli Capture"). The third stage was the "author a configuration document with Customer Success" step, dropped in 0a1e3f9 when the configuration-document model went away — the count was not updated with it. A reader counting stages stops and looks for the missing one.

Suggested change

	Getting started with Kosli Capture involves three stages:
	<Steps>
	<Step title="Prepare your environment">
	Create an IAM role in your AWS account specifically for Kosli Capture. Kosli provides a CloudFormation template to simplify this process. The template requires a shared secret, which Kosli provides to you.
	</Step>
	<Step title="Enable Kosli Capture">
	Enable Kosli Capture for your Kosli org, and the regular snapshots appear in Kosli.
	</Step>
	</Steps>
	Getting started with Kosli Capture involves two stages:
	<Steps>
	<Step>
	Create an IAM role in your AWS account specifically for Kosli Capture. Kosli provides a CloudFormation template to simplify this process. The template requires a shared secret, which Kosli provides to you.
	</Step>
	<Step>
	Enable Kosli Capture for your Kosli org, and the regular snapshots appear in Kosli.
	</Step>
	</Steps>

[claude]

Improvement — this sentence still describes the tag-mapping configuration that 0a1e3f9 removed. "provide configuration details for how your tags should map to environments within Kosli" is contradicted three ways at this branch head:

• overview.md:18 now says Kosli Capture "uses details about your infrastructure, such as the name of an ECS cluster, to build environments" — names, not tags.
• overview.md:38 reduces tags to exclusion only ("can filter out resources based on AWS tags"), which matches this page's own "Excluding resources" section and the kosli.capture=false tag at line 43.
• This page's <Steps> and body have no configuration stage at all — line 39 says you simply activate it in the UI.

So the one thing this intro tells the reader to prepare is the one thing the page never asks them to do. It is also the first paragraph, which makes it the most likely sentence to be believed.

Suggested change

	Kosli Capture is a managed service that runs on Kosli's infrastructure and connects to your cloud platform to observe the resources deployed there. To get step up with Kosli Capture you need to grant permissions to Kosli's cloud account and provide configuration details for how your tags should map to environments within Kosli.
	Kosli Capture is a managed service that runs on Kosli's infrastructure and connects to your cloud platform to observe the resources deployed there. To get set up with Kosli Capture you need to grant permissions to Kosli's cloud account, then enable Kosli Capture for your organization in the Kosli UI.

[claude]

Improvement — the CloudFormation template is the one artifact this page cannot be followed without, and it is still never linked. It is named nine times across the three new pages, and security.md:14 now goes further: "The template is publicly accessible and can be used directly within an aws cloudformation create-stack call." A reader who takes that at face value has no URL to pass to --template-url, and no way to review the permissions before involving Customer Success.

This matters more here than on the other two pages, because getting_started.md is the only how-to of the three — a how-to whose first stage cannot be completed from the page.

If the URL is public, link it here and on security.md, and show the create-stack (and create-stack-set) invocation, since lines 31–33 already describe both the single-account and OU/StackSet paths. If it is not published yet, say "Kosli provides the template during onboarding" so the reader stops looking for it.

Line 20 has a related gap in the other direction: it says "The template requires a shared secret, which Kosli provides to you", while line 31 says "each organization within Kosli has its own external Id" — same thing under two names, and neither says how you obtain it. Unify on "external ID" (the term security.md:41 and overview.md:50 both use) and name the channel.

[claude]

Improvement — "according to rules you define" is stale, and the section sits outside this page's declared scope.

Two separate problems:

1. The claim no longer matches the linked page. 0a1e3f9 removed the user-authored configuration document; at this branch head kosli_capture/overview.md:18 says you configure Kosli Capture "by activating it for different AWS services", and getting_started.md:39 is a UI toggle. There are no rules you define — the only reader-controlled input left is the kosli.capture=false exclusion tag. A reader follows this link expecting a rules format and finds none.
2. Scope clash. Line 13 tells the reader "This page covers managing environments via Terraform. For creating environments via the CLI or UI, see [Getting started: Environments]". Kosli Capture is none of the three, so the section needs to say why it is here. The H3 nesting under "Managing physical environments" is right.

Present tense also reads better than "will automatically snapshot" / "will create" for a capability that exists today.

Suggested change

	### Automatically creating physical environments
	The [Kosli Capture Managed Service](/administration/kosli_capture/overview) will automatically snapshot your infrastructure according to rules you define. Kosli Capture will create physical environments as needed.
	### Automatically creating physical environments
	The [Kosli Capture Managed Service](/administration/kosli_capture/overview) creates physical environments for you, without Terraform. It snapshots the supported resources in your AWS accounts on a schedule and creates the environments it needs as it discovers them.

[claude]

Improvement — GCP and Azure are claimed only here, and nothing on any of the three pages gives those readers a mechanism.

This says Kosli Capture "uses the public AWS, GCP and Azure APIs", but every mechanism described across the new folder is AWS-only: an IAM role, a CloudFormation template, an sts:AssumeRole trust policy, and ECS + Lambda policy statements. overview.md:36 says "supported resources within your AWS accounts"; overview.md:44 says "multiple AWS regions and accounts"; getting_started.md:29 says "your ECS clusters and Lambdas".

This became the only provider-scope statement on the site when 7afa53c dropped the Current status section ("Support for … other cloud providers is in active development"), which used to be what kept the claim honest. A reader on GCP or Azure is now told their provider's API is used, reads a page of AWS IAM, and has no way to grant access or to tell that they are out of scope today.

Suggested change

The Kosli Capture managed service uses the public AWS, GCP and Azure APIs to extract information about your cloud environments. In order to do this, you need to provide Kosli with an IAM role that allows access to these APIs. The role is created and owned by you. Kosli publishes a CloudFormation template, for use in AWS, showing the permissions needed. The template is publicly accessible and can be used directly within an `aws cloudformation create-stack` call.

The Kosli Capture managed service uses the public AWS APIs to extract information about your cloud environments. To do this, you provide Kosli with an IAM role that allows access to these APIs. The role is created and owned by you. Kosli publishes a CloudFormation template showing the permissions needed, which you can use directly in an `aws cloudformation create-stack` call.

Related, and the reason the scope statement is load-bearing: with Current status gone, the supported resource types are no longer stated anywhere on the site. overview.md:36 says "all supported resources" without defining the set, overview.md:40 uses ECS and Lambda only as incidental examples, and the IAM policy below is now the sole authoritative signal (ECS + Lambda; S3 removed in b6dd574). One sentence on overview.md naming the types would restore what the removed section provided, and gives you an obvious place to update when S3 or EKS lands.

[claude]

Improvement — this section still refers to an unnamed "customer A". Line 24 reads "Only that role is permitted to call AssumeRole into A's account with A's ExternalId." Nothing on the page defines "A" — it reads as a leftover from an internal design document where customers were labelled A and B. This is the section a reader is most likely to forward to their own security team, and it contains an unresolvable referent in its first bullet.

Three more defects in the same block:

• Line 22 has no closing full stop ("...scoped to one customer").
• Line 28 spells the product "Kosli Catpure" twice. Worth flagging because vale-spellcheck cannot catch it: .vale.ini sets BasedOnStyles = Kosli and styles/Kosli/ contains only AmericanSpelling.yml, so there is no general dictionary on this repo.
• The page uses "ExternalId" here and "external ID" at lines 50–52; security.md:41 uses the YAML key sts:ExternalId. Reserve the camel-case form for the literal key and use "external ID" in prose.

Suggested change

	The security of your cloud infrastructure is the primary driver behind the internal architecture of the Kosli Capture managed service. Kosli Capture runs as a shared, autoscaled service, but each job runs under a role that is scoped to one customer
	* A Kosli Capture worker picks up a job for your organization and assumes a Kosli-side role that exists only for your organization. Only that role is permitted to call AssumeRole into A's account with A's ExternalId.
	* When the job finishes, those credentials are discarded. A worker holding credentials for your cloud account has no path to anyone else's account.
	* The trust policy's ExternalId lives in Parameter Store and is readable only by the Kosli-side role for your organization. The shared task role cannot read any customer's ExternalId. Separation is enforced by IAM, not by application code.
	Kosli Catpure itself does not hold any customer data. Snapshots taken by Kosli Catpure are immediately sent to Kosli through the same ingest path as your existing pipelines.
	The security of your cloud infrastructure is the primary driver behind the internal architecture of the Kosli Capture managed service. Kosli Capture runs as a shared, autoscaled service, but each job runs under a role that is scoped to a single customer.
	* A Kosli Capture worker picks up a job for your organization and assumes a Kosli-side role that exists only for your organization. Only that role is permitted to call `AssumeRole` into your account, with your external ID.
	* When the job finishes, those credentials are discarded. A worker holding credentials for your cloud account has no path to any other account.
	* The trust policy's external ID lives in Parameter Store and is readable only by the Kosli-side role for your organization. The shared task role cannot read any customer's external ID. Separation is enforced by IAM, not by application code.
	Kosli Capture itself does not hold any customer data. Snapshots taken by Kosli Capture are immediately sent to Kosli through the same ingest path as your existing pipelines.

[claude]

Suggestion — now that the pages are split, decide which one owns the trust policy. 6e1d5c5 gave Kosli Capture its own folder with security.md as a sibling, but this overview still carries two sections on the same subject: ## Security (lines 20–28, the worker/role isolation model) and this one. Lines 50–52 are a prose restatement of the AssumeRolePolicyDocument block that security.md:22–42 shows in full — the two will drift, and the external-ID storage claim is already worded differently in each.

A reasonable split: the overview says in two sentences what access is needed and why it is safe, and security.md owns the mechanism. Note also that security.md has no link back here, so the pair is navigable only via the sidebar.

Two things on line 48 itself: "deep-diver" should be "deep dive", and there is a double space before "The".

Suggested change

	## IAM permissions
	For Kosli Capture to snapshot your environment, you must grant a set of read-only permissions. Kosli's CloudFormation template lists these. The permissions are typically "Describe" or "List" permissions. The [Kosli Capture Security](/administration/kosli_capture/security) page provides a deep-diver into the structure of the permissions needed.
	The IAM role created in your environment includes a trust policy that allows Kosli Capture to assume the role. The trust policy limits access to the AWS account in which Kosli Capture is running. Furthermore, the trust policy includes an external ID that acts as a shared secret between Kosli and you, so that only access from Kosli Capture is permitted.
	The external ID (shared secret) is securely stored with Kosli Capture. Kosli's internal IAM permissions ensure that the secret can only be accessed by the specific instance of Kosli Capture worker that is operating for you.
	## IAM permissions
	For Kosli Capture to snapshot your environment, you must grant a set of read-only permissions. Kosli's CloudFormation template lists these, and they are typically "Describe" or "List" permissions.
	The IAM role you create includes a trust policy that allows only Kosli Capture to assume it, using an external ID that acts as a shared secret between you and Kosli. The [Kosli Capture security](/administration/kosli_capture/security) page is a deep dive into the role, the trust policy, and the full permission list.

[claude]

Suggestion — stray fourth backtick, no language tags, and the S3 removal left this deny unexplained.

The closing fence is ```` (four backticks). CommonMark still terminates the block so the page renders, but it is a stray character on the final line.

Neither code block on this page declares a language (openers at lines 22 and 48), so a page that is entirely YAML gets no syntax highlighting — worth making both ```yaml.

Substantively: b6dd574 removed the S3BucketMetadataOnly allow and the NeverReadObjectData deny, and with them the comment that explained why explicit denies appear in an allow-list policy at all ("redundant given the allow-list above, but they are here so that a reviewer can verify the boundary without having to reason about IAM defaults"). NeverDownloadFunctionCode is now the only deny among allows: its comment says what it blocks, but not why a deny is used rather than simply omitting the action. On a page whose entire purpose is passing someone else's security review, that rationale was the valuable half.

Suggested change

	````
	# lambda:GetFunction returns a pre-signed URL to the deployment
	# package. That is source-code access, so it is denied outright.
	# The deny is redundant given the allow-list above, but it is here
	# so that a reviewer can verify the boundary without reasoning
	# about IAM defaults, and so that any future widening of this
	# policy cannot accidentally grant code access.
	- Sid: NeverDownloadFunctionCode
	Effect: Deny
	Action:
	- lambda:GetFunction
	- lambda:GetLayerVersion
	Resource: "*"

[claude]

Critical — the first paragraph tells the reader to prepare something the page never asks for.

"provide configuration details for how your tags should map to environments within Kosli" is contradicted three ways at this branch head:

• overview.md:20 says you configure Kosli Capture "by activating it for different AWS services", and that it "uses details about your infrastructure, such as the name of an ECS cluster, to build environments" — names, not a tag map.
• This page's own two stages are an IAM role and a UI toggle (lines 27–39). There is no configuration stage.
• The only reader-controlled tag left is the kosli.capture=false exclusion tag at line 43 — filtering, not mapping.

This is the tag-mapping configuration document that 0a1e3f9 removed; the intro was not updated with it. Being the opening sentence of the only how-to page in the group, it is the sentence most likely to be acted on.

Suggested change

	Kosli Capture is a managed service that runs on Kosli's infrastructure and connects to your cloud platform to observe the resources deployed there. To get set up with Kosli Capture you need to grant permissions to Kosli's cloud account and provide configuration details for how your tags should map to environments within Kosli.
	Kosli Capture is a managed service that runs on Kosli's infrastructure and connects to your cloud platform to observe the resources deployed there. To get set up with Kosli Capture you need to grant permissions to Kosli's cloud account, then enable Kosli Capture for your organization in the Kosli UI.

[claude]

Improvement — GCP and Azure are claimed only here, and no page gives those readers a mechanism.

Every mechanism across the folder is AWS-only: an IAM role, a CloudFormation template, an sts:AssumeRole trust policy, and ECS + Lambda policy statements. overview.md:38 says "within your AWS accounts"; overview.md:46 says "multiple AWS regions and accounts"; getting_started.md:29 says "your ECS clusters and Lambdas".

This became the only provider-scope statement on the site when 7afa53c dropped the Current status section, which used to keep the claim honest ("Support for … other cloud providers is in active development"). A reader on GCP or Azure is now told their provider's API is used, reads a page of AWS IAM, and has no way to tell they are out of scope today.

Second thing in the same sentence: "The template is publicly accessible and can be used directly within an aws cloudformation create-stack call" is the most actionable line on the page, but the template is named nine times across the three pages and never linked. There is no URL to pass to --template-url. If it is public, link it here and at getting_started.md:31; if not, say "Kosli provides the template during onboarding" so the reader stops looking.

Suggested change

The Kosli Capture managed service uses the public AWS, GCP and Azure APIs to extract information about your cloud environments. In order to do this, you need to provide Kosli with an IAM role that allows access to these APIs. The role is created and owned by you. Kosli publishes a CloudFormation template, for use in AWS, showing the permissions needed. The template is publicly accessible and can be used directly within an `aws cloudformation create-stack` call.

The Kosli Capture managed service uses the public AWS APIs to extract information about your cloud environments. In order to do this, you need to provide Kosli with an IAM role that allows access to these APIs. The role is created and owned by you. Kosli publishes a CloudFormation template showing the permissions needed, which you can use directly within an `aws cloudformation create-stack` call.

[claude]

Improvement — this section still refers to an unnamed "customer A".

Line 26 reads "Only that role is permitted to call AssumeRole into A's account with A's ExternalId". Nothing on the page defines "A" — it reads as a leftover from an internal design document where customers were labelled A and B. This is the section a reader is most likely to forward to their own security team, and the referent is unresolvable in its first bullet.

Also in this block: line 24 has no closing full stop, line 30 spells the product "Kosli Catpure" twice, and the page uses "ExternalId" here but "external ID" at lines 52–54 — worth reserving the camel-case form for the literal YAML key shown at security.md:41.

Suggested change

	The security of your cloud infrastructure is the primary driver behind the internal architecture of the Kosli Capture managed service. Kosli Capture runs as a shared, autoscaled service, but each job runs under a role that is scoped to one customer
	* A Kosli Capture worker picks up a job for your organization and assumes a Kosli-side role that exists only for your organization. Only that role is permitted to call AssumeRole into A's account with A's ExternalId.
	* When the job finishes, those credentials are discarded. A worker holding credentials for your cloud account has no path to anyone else's account.
	* The trust policy's ExternalId lives in Parameter Store and is readable only by the Kosli-side role for your organization. The shared task role cannot read any customer's ExternalId. Separation is enforced by IAM, not by application code.
	Kosli Catpure itself does not hold any customer data. Snapshots taken by Kosli Catpure are immediately sent to Kosli through the same ingest path as your existing pipelines.
	The security of your cloud infrastructure is the primary driver behind the internal architecture of the Kosli Capture managed service. Kosli Capture runs as a shared, autoscaled service, but each job runs under a role that is scoped to a single customer.
	* A Kosli Capture worker picks up a job for your organization and assumes a Kosli-side role that exists only for your organization. Only that role is permitted to call `AssumeRole` into your account, with your external ID.
	* When the job finishes, those credentials are discarded. A worker holding credentials for your cloud account has no path to anyone else's account.
	* The trust policy's external ID lives in Parameter Store and is readable only by the Kosli-side role for your organization. The shared task role cannot read any customer's external ID. Separation is enforced by IAM, not by application code.
	Kosli Capture itself does not hold any customer data. Snapshots taken by Kosli Capture are immediately sent to Kosli through the same ingest path as your existing pipelines.

[claude]

Improvement — "all supported resources" is undefined, and line 42 still points at a configuration that no longer exists.

Two stale references from the same removals:

1. Supported resource types. 7afa53c dropped the Current status section, which was the only statement of what Kosli Capture can snapshot. Line 38 now says "all supported resources" without defining the set; line 42 uses ECS and Lambda only as incidental examples. The authoritative signal is the IAM policy on security.md (ECS + Lambda; S3 removed in b6dd574) and a passing mention at getting_started.md:29. A reader evaluating the service on the page meant for evaluating it cannot tell what it covers.
2. "No changes to the configuration created during the initial setup are required." 0a1e3f9 removed the user-authored configuration document. Initial setup is now an IAM role plus a UI toggle — there is no configuration to leave unchanged. The sentence before it is also circular: it gives "Kosli Capture creates physical environments as needed" as the reason Kosli keeps up, having already asserted the same thing on line 38.

Suggested change

	Kosli Capture finds all supported resources within your AWS accounts, and determines which Kosli environment should hold the snapshots. Kosli Capture will create physical environments for you.
	Kosli Capture can [filter out resources based on AWS tags](/administration/kosli_capture/getting_started#excluding-resources).
	As your cloud environment evolves, such as the addition of new ECS clusters or the retirement of existing Lambdas, Kosli Capture automatically detects the changes. Because Kosli Capture creates physical environments as needed, when your infrastructure changes, Kosli will keep up. No changes to the configuration created during the initial setup are required.
	Kosli Capture currently snapshots ECS clusters and Lambda functions. It finds these resources within your AWS accounts and determines which Kosli environment should hold the snapshots.
	Kosli Capture can [filter out resources based on AWS tags](/administration/kosli_capture/getting_started#excluding-resources).
	As your cloud environment evolves, such as the addition of new ECS clusters or the retirement of existing Lambdas, Kosli Capture automatically detects the changes and creates any new physical environments needed. You do not need to change anything you set up when you enabled it.

[claude]

Improvement — "according to rules you define" no longer matches the page it links to.

0a1e3f9 removed the user-authored configuration document. At this branch head kosli_capture/overview.md:20 says you configure Kosli Capture "by activating it for different AWS services", and getting_started.md:39 is a UI toggle. There are no rules you define — the only reader-controlled input left is the kosli.capture=false exclusion tag. A reader follows this link expecting a rules format and finds none.

Two smaller points on the same block: the H3 nesting under "Managing physical environments" is right, but line 13 tells the reader "This page covers managing environments via Terraform", and Kosli Capture is neither Terraform, CLI, nor UI — saying so explicitly stops the section reading as misfiled. And the two sibling H3s are imperative ("Create a physical environment", "Import an existing physical environment"), so a gerund heading stands out.

Suggested change

	The [Kosli Capture Managed Service](/administration/kosli_capture/overview) will automatically snapshot your infrastructure according to rules you define. Kosli Capture will create physical environments as needed.
	### Create physical environments automatically
	The [Kosli Capture Managed Service](/administration/kosli_capture/overview) creates physical environments for you, without Terraform. It snapshots the supported resources in your AWS accounts on a schedule and creates the environments it needs as it discovers them.

[claude]

Improvement — now that the pages are split, decide which one owns the trust policy.

6e1d5c5 gave Kosli Capture its own folder with security.md as a sibling, but this overview still carries two sections on the same subject: ## Security (lines 22–30, the worker/role isolation model) and this one. Lines 52–54 are a prose restatement of the AssumeRolePolicyDocument that security.md:22–42 shows in full, and the external-ID storage claim is already worded differently in the two places — they will drift.

A workable split: the overview says in two sentences what access is needed and why it is safe, and security.md owns the mechanism. Note security.md has no link back here either, so the pair is navigable only via the sidebar.

Line 50 also has "deep-diver" for "deep dive", and a double space before "The".

Suggested change

	## IAM permissions
	For Kosli Capture to snapshot your environment, you must grant a set of read-only permissions. Kosli's CloudFormation template lists these. The permissions are typically "Describe" or "List" permissions. The [Kosli Capture Security](/administration/kosli_capture/security) page provides a deep-diver into the structure of the permissions needed.
	The IAM role created in your environment includes a trust policy that allows Kosli Capture to assume the role. The trust policy limits access to the AWS account in which Kosli Capture is running. Furthermore, the trust policy includes an external ID that acts as a shared secret between Kosli and you, so that only access from Kosli Capture is permitted.
	The external ID (shared secret) is securely stored with Kosli Capture. Kosli's internal IAM permissions ensure that the secret can only be accessed by the specific instance of Kosli Capture worker that is operating for you.
	## IAM permissions
	For Kosli Capture to snapshot your environment, you must grant a set of read-only permissions. Kosli's CloudFormation template lists these, and they are typically "Describe" or "List" permissions.
	The IAM role you create includes a trust policy that allows only Kosli Capture to assume it, using an external ID that acts as a shared secret between you and Kosli. The [Kosli Capture security](/administration/kosli_capture/security) page is a deep dive into the role, the trust policy, and the full permission list.

[claude]

Suggestion — stray fourth backtick, no language tags, and the S3 removal left this deny unexplained.

The closing fence here is ```` (four backticks). CommonMark still terminates the block so the page renders, but it is a stray character on the final line.

Neither code block declares a language (openers at lines 22 and 48), so a page that is entirely YAML gets no syntax highlighting — worth making both ```yaml.

Substantively: b6dd574 removed the S3BucketMetadataOnly allow and the NeverReadObjectData deny, and with them the comment explaining why explicit denies appear in an allow-list policy at all ("redundant given the allow-list above, but they are here so that a reviewer can verify the boundary without having to reason about IAM defaults"). NeverDownloadFunctionCode is now the only deny among allows — its comment says what it blocks, but not why a deny rather than simply omitting the action. On a page whose purpose is passing someone else's security review, that rationale was the valuable half.

Suggested change

````

[gsavage]

We've had two complete redesigns of the service since this PR was first opened. I'm closing the PR now and opening a new one with a single squashed commit on it, so that the reviewer isn't working through lots of out-of-date comments.