feat: add docs for Kosli Capture Managed Service

[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 16, 2026, 9:44 AM

[claude]

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

---

Doc review

Re-reviewed at 7c895f0. Two findings from the previous pass are fixed and not repeated here (handed → handled, and the mismatched code-fence backticks — both blocks are now tagged ```yaml). All three new pages are listed in config/navigation.json, all internal links are root-relative and resolve, and no page was moved or deleted, so no config/redirects.json entry is needed.

---

Improvements

1. The CloudFormation template has two different origins, and neither is followable — administration/kosli_capture/getting_started.md:31, administration/kosli_capture/security.md:14

Still open from the previous pass.

• getting_started.md:31 — "can be downloaded from the Settings page for your organization within the Kosli UI"
• security.md:14 — "publicly accessible and can be used directly within an aws cloudformation create-stack call"

One of these is wrong, and neither gives a URL or a UI navigation path, so a reader cannot complete step 1 of the only setup page. Compounding it: the template takes TrustedPrincipalArn and ExternalId as parameters (security.md:37,41), and getting_started.md never says what to pass for either — security.md:14's "used directly" is only true once you have both. If the template is public and the ExternalId is a per-org secret Kosli hands you, say so in one place and have the other page point at it.

Pick one source of truth, state it identically on both pages, and add the public S3/HTTPS URL if there is one. Fix this →

2. "All supported resources" is never resolved to a list — administration/kosli_capture/overview.md:38

Still open from the previous pass, and the new entry point makes it sharper. getting_started/environments.md:58 now appends "Kosli can also report these snapshots for you, using the Kosli Capture Managed Service" directly after the list of eight supported environment types — Kubernetes, S3, Azure Web Apps, Cloud Run and the rest. But the IAM policy in security.md grants ECS and Lambda permissions only. A reader arriving from that sentence will reasonably conclude their Kubernetes clusters are covered.

The overview never names a resource type in its own right; ECS and Lambda appear only incidentally at overview.md:20,42 and in getting_started.md:29. administration/managing_environments/overview.md:69 repeats the same unresolved phrase ("the supported resources it finds").

Name the supported types explicitly in Finding resources — ECS and Lambda for this beta — and qualify the sentence at getting_started/environments.md:58 so it doesn't read as covering the whole list above it. Fix this →

Suggestions

3. New Terraform-page section leaves the drift question unanswered — administration/managing_environments/overview.md:69 (inline)

4. Multi-region is promised but not explained — administration/kosli_capture/overview.md:46 (inline)

---

2 Improvements, 2 Suggestions, 0 Critical. Nothing blocks the merge given the BETA framing and the stated goal of gathering feedback early — but finding 1 makes the getting-started page unusable as written, so it is worth closing before this ships even as a beta page.
· branch kosli-capture-docs

[dangrondahl]

Kosli publishes a CloudFormation template, for use in AWS, showing the permissions needed

Where is this publicly accessible?

[gsavage]

It will be - Claude asked me the same thing :-)

I didn't want to include a link to the template yet because it is still being worked on. But yes, it will be in an S3 bucket with a public-read policy. A link to the template will be included in the new settings screen.

[gsavage]

Feedback from a customer, this morning, was that they don't want to use CloudFormation. A Terraform module might work for them, otherwise they will handle the creation of the role.

Based on that feedback, I think we may want to restructure this page -- it currently mixes CloudFormation and security in the same document.

[dangrondahl]

What is CS role on onboarding, or could it be self-serviceable?

[gsavage]

The design and rollout of Kosli Capture is still being designed. When I wrote that sentence originally, I imagined writing a play-book for CS. We now appear to be converging on a process that shouldn't need much/any CS involvement.

That sentence was added to help customers understand that this isn't something they can do themselves yet.

[dangrondahl]

I wonder, what if security permissions change?

[gsavage]

If the permissions we need change (for example we realise we need to read tags), then Kosli Capture might not work for the customer until they update their IAM role.

If the customer changes the IAM role and removes permissions we require, then Kosli Capture will stop working.

Do you think we need to include this in the documentation today?