Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions .claude/skills/connector-docs.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
---
name: c1-connector-docs
description: Write connector documentation for C1 following the established template structure. Use when creating new connector docs in /baton/, updating existing connector pages, or reviewing connector documentation. Ensures consistency with the standardized connector doc format including capabilities tables, credential gathering, and cloud/self-hosted configuration tabs.
description: Write connector documentation for C1.ai following the established template structure. Use when creating new connector docs in /baton/, updating existing connector pages, or reviewing connector documentation. Ensures consistency with the standardized connector doc format including capabilities tables, credential gathering, and cloud/self-hosted configuration tabs.
---

# C1 Connector Documentation
# C1.ai Connector Documentation

> **Heads up:** A copy of this skill also lives in [`ConductorOne/baton-admin`](https://github.com/ConductorOne/baton-admin/blob/main/pkg/files/.claude/skills/connector/build-connector-docs.md). If you update this file, copy the changes there too.

Write connector documentation for the `/baton/` directory following C1's standardized template.
Write connector documentation for the `/baton/` directory following C1.ai's standardized template.

## When to Use This Skill

Expand All @@ -19,7 +19,7 @@ Use this skill when:

## File Format

**Location:** Connector docs live in the connector's GitHub repository in the [C1 organization](https://github.com/ConductorOne), not in this docs repo. Search for the connector repo by name (e.g., `baton-okta`, `baton-salesforce`) to find the right repo.
**Location:** Connector docs live in the connector's GitHub repository in the [C1.ai organization](https://github.com/ConductorOne), not in this docs repo. Search for the connector repo by name (e.g., `baton-okta`, `baton-salesforce`) to find the right repo.

**Naming:** The doc file should be named `docs.mdx` and placed in the root or a `docs/` directory of the connector repo, following the convention already established in that repo.

Expand Down Expand Up @@ -156,7 +156,7 @@ The [App Name] connector supports [automatic account provisioning](/product/admi

### Connector Actions Section (if applicable)

Some connectors support custom actions that can be used in C1 automations. Add this section after the Capabilities table if the connector supports actions.
Some connectors support custom actions that can be used in C1.ai automations. Add this section after the Capabilities table if the connector supports actions.

```mdx
### Connector actions
Expand Down Expand Up @@ -359,15 +359,15 @@ For more information, see [link to vendor docs].
name: baton-[connector-name]-secrets
type: Opaque
stringData:
# C1 credentials
BATON_CLIENT_ID: <C1 client ID>
BATON_CLIENT_SECRET: <C1 client secret>
# C1.ai credentials
BATON_CLIENT_ID: <C1.ai client ID>
BATON_CLIENT_SECRET: <C1.ai client secret>

# [App Name] credentials
BATON_[APP]_[CREDENTIAL_1]: <Your [credential 1]>
BATON_[APP]_[CREDENTIAL_2]: <Your [credential 2]>

# Optional: include if you want C1 to provision access using this connector
# Optional: include if you want C1.ai to provision access using this connector
BATON_PROVISIONING: true
```

Expand Down
38 changes: 19 additions & 19 deletions .claude/skills/docs-writing.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,28 @@
---
name: c1-docs-writer
description: Write documentation for C1's website following established voice, tone, and style guidelines. Use when creating new documentation pages, updating existing docs, writing how-to guides, or any content for conductorone.com/docs. Ensures consistency with C1's direct, action-oriented documentation style.
description: Write documentation for C1.ai's website following established voice, tone, and style guidelines. Use when creating new documentation pages, updating existing docs, writing how-to guides, or any content for conductorone.com/docs. Ensures consistency with C1.ai's direct, action-oriented documentation style.
---

# C1 Documentation Writer
# C1.ai Documentation Writer

Write C1 documentation that matches the established voice, tone, and style of the existing docs site.
Write C1.ai documentation that matches the established voice, tone, and style of the existing docs site.

## When to Use This Skill

Use this skill when:
- Creating new documentation pages for C1
- Creating new documentation pages for C1.ai
- Writing or updating how-to guides
- Drafting admin guides or end-user documentation
- Creating quickstart guides
- Writing any content intended for conductorone.com/docs

## The docs voice

Documentation has a different job than marketing. Marketing makes a case for C1. Docs assume the reader already chose C1 — they're here to get something done. The voice shifts accordingly: less energetic, more instructive.
Documentation has a different job than marketing. Marketing makes a case for C1.ai. Docs assume the reader already chose C1.ai — they're here to get something done. The voice shifts accordingly: less energetic, more instructive.

**Outside-in framing.** Lead with what the reader is trying to accomplish, not with the feature name or how it works internally. "If you run recurring campaigns, use a template to avoid reconfiguring from scratch each time" is outside-in. "Campaign templates are a feature that allows..." is not. The opening sentence of every page should tell the reader what they can *do* after reading it — not what the feature *is*.

**Declarative, not hedged.** If something is true, say it plainly. Don't write "C1 can help streamline the approval process." Write "C1 auto-approves requests that meet policy." Hedging makes docs feel uncertain; readers lose confidence in the product.
**Declarative, not hedged.** If something is true, say it plainly. Don't write "C1.ai can help streamline the approval process." Write "C1.ai auto-approves requests that meet policy." Hedging makes docs feel uncertain; readers lose confidence in the product.

**Peer-level respect.** The reader is a security or IT professional. They know why access reviews matter. They need to know how to run one. Skip context they already have and get to the task.

Expand All @@ -31,7 +31,7 @@ Documentation has a different job than marketing. Marketing makes a case for C1.
- Do: "New tasks will now be automatically reassigned to your delegate."
- Don't: "That's it! Tasks will now be assigned to your delegate."

**Active voice, specific verbs.** "C1 sends a notification" not "a notification is sent." "Click **Save**" not "the Save button should be clicked."
**Active voice, specific verbs.** "C1.ai sends a notification" not "a notification is sent." "Click **Save**" not "the Save button should be clicked."

**Avoid hedging verbs.** These drain sentences of authority:
- "helps you to" → use a direct verb
Expand All @@ -45,7 +45,7 @@ Documentation has a different job than marketing. Marketing makes a case for C1.

## File Format

**Always use .mdx format** for C1 documentation files. MDX (Markdown with JSX) is the required format for the docs site. When creating new documentation, save files with the `.mdx` extension.
**Always use .mdx format** for C1.ai documentation files. MDX (Markdown with JSX) is the required format for the docs site. When creating new documentation, save files with the `.mdx` extension.

### Content Structure

Expand All @@ -56,7 +56,7 @@ Documentation has a different job than marketing. Marketing makes a case for C1.

## File and Folder Structure

C1 docs use Mintlify, where **file path = URL**. Structure decisions are permanent without redirects, so be intentional.
C1.ai docs use Mintlify, where **file path = URL**. Structure decisions are permanent without redirects, so be intentional.

### Folder rules

Expand Down Expand Up @@ -95,7 +95,7 @@ Sidebar grouping in `docs.json` is independent of folder structure. You can visu
- Are there any hedging verbs, editorializing phrases, or throat-clearing openers?
- Does any sentence try to serve too many stakeholders at once? Split it or cut it.
- After each procedure, is there an outcome sentence stating what changed?
- Is the company name "C1" throughout?
- Is the company name "C1.ai" throughout?

## Key Style Points

Expand Down Expand Up @@ -211,14 +211,14 @@ When documenting features that are in early access, add a standardized warning c

**Key points:**
- Always use `<Warning>` (not `<Info>` or `<Note>`)
- Always use "the C1 Support team" (not "our Support team" or "your account team")
- Always use "the C1.ai Support team" (not "our Support team" or "your account team")
- Don't name the specific feature (use "This feature")
- Include the explanation of what early access means
- Use "share feedback" (not "have any feedback")

## Hosting region references (default instance vs. EU data residency)

C1 runs two hosting options — a **default instance** (`conductor.one`) and an **EU data residency instance** (`c1eu.ai`). A tenant is provisioned in one region, and every tenant-specific URL, hostname, or IP address reflects it. See the "Hosting regions" table in [Create a C1 tenant](/product/how-to/qs-set-up-c1) for the canonical explainer — link there rather than re-explaining the concept on other pages.
C1.ai runs two hosting options — a **default instance** (`conductor.one`) and an **EU data residency instance** (`c1eu.ai`). A tenant is provisioned in one region, and every tenant-specific URL, hostname, or IP address reflects it. See the "Hosting regions" table in [Create a C1.ai tenant](/product/how-to/qs-set-up-c1) for the canonical explainer — link there rather than re-explaining the concept on other pages.

Anywhere a region-specific value appears, use one of the two treatments below based on how the value is used — not on which section of the docs it's in.

Expand All @@ -229,9 +229,9 @@ Anywhere a region-specific value appears, use one of the two treatments below ba
- EU data residency instance: `https://accounts.c1eu.ai/auth/callback`
```

Lead into the pair with wording that tells the reader how to choose — "whichever matches your C1 tenant's domain" — rather than assuming they already know which hosting option they're on. This applies even when the value is tenant-specific (contains a placeholder like `<tenantName>` or `YOUR_DOMAIN`): show both domain suffixes, not just `conductor.one`.
Lead into the pair with wording that tells the reader how to choose — "whichever matches your C1.ai tenant's domain" — rather than assuming they already know which hosting option they're on. This applies even when the value is tenant-specific (contains a placeholder like `<tenantName>` or `YOUR_DOMAIN`): show both domain suffixes, not just `conductor.one`.

Don't use this pattern for a value the reader copies directly from their own C1 account (for example, an MCP server URL shown on an "AI connections" page) — the product already displays the tenant's real, region-correct value, so there's nothing to disambiguate.
Don't use this pattern for a value the reader copies directly from their own C1.ai account (for example, an MCP server URL shown on an "AI connections" page) — the product already displays the tenant's real, region-correct value, so there's nothing to disambiguate.

**Reference and example-heavy pages** (API docs, CLI docs, service-principal/workload-federation guides) where `conductor.one` appears repeatedly inside code blocks or curl examples — don't rewrite every example. Add one callout near the section the examples belong to instead:

Expand All @@ -255,15 +255,15 @@ Don't use this pattern for a value the reader copies directly from their own C1

## Product name

Always use **C1** to refer to the product and company in prose. Do not use "ConductorOne" in new documentation.
Always use **C1.ai** to refer to the product and company in prose. Do not use "ConductorOne" in new documentation.

**Marketing website:** The marketing website is **c1.ai** — use this for any links to the public marketing site. Do not use `conductorone.com` for marketing links.

**Exceptions — never change these to C1:**
**Exceptions — never change these to C1.ai:**

| What | Examples |
| :--- | :--- |
| Product and tenant URLs | `conductor.one`, tenant URLs like `example.conductor.one` |
| Product and tenant URLs | `conductor.one`, tenant URLs like `example.conductor.one`, and `c1eu.ai` (the EU data-residency domain) |
| File and directory paths generated by tools | `~/.conductorone/config.yaml` |
| Code identifiers | Environment variables (`CONDUCTORONE_CLIENT_ID`), package names, binary names |
| GitHub organization in URLs | `github.com/ConductorOne/...` |
Expand All @@ -272,14 +272,14 @@ When in doubt: if a user would type it into a terminal or config file, leave it

## Common Mistakes to Avoid

- **Hedging verbs**: "helps you to," "can help," "is designed to," "allows you to" — use direct verbs instead ("lets you," "C1 does X")
- **Hedging verbs**: "helps you to," "can help," "is designed to," "allows you to" — use direct verbs instead ("lets you," "C1.ai does X")
- **Feature-first openers**: "Campaign templates are a feature that allows..." → lead with what the reader can do instead
- **Celebrating task completion**: "That's it!", "Done.", "You're all set!" → state the outcome
- **Multi-clause sentences serving too many stakeholders at once** — split or cut
- **Editorializing**: "it's important to note," "it's worth mentioning," "please note"
- **Promotional language**: "powerful," "robust," "seamless," "innovative"
- **Excessive conjunctions**: "moreover," "furthermore," "additionally"
- **Using "ConductorOne"** instead of "C1" in prose
- **Using "ConductorOne"** instead of "C1.ai" in prose
- **Using "bool"** — use "Boolean"
- **Title case in headings** — sentence case only
- **Context-free headings** like "FAQ" or "Related" — always include the subject ("Frequently asked questions about automations")
Expand Down
4 changes: 2 additions & 2 deletions .claude/skills/rap-documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,9 +120,9 @@ RAP files target LLM agents, not humans. Write differently than human-facing doc

**Example contrast:**

Human docs: "The Baton connector framework solves this elegantly: you write one integration, and C1 handles the rest."
Human docs: "The Baton connector framework solves this elegantly: you write one integration, and C1.ai handles the rest."

RAP docs: "A connector translates access data from any system into C1's common format."
RAP docs: "A connector translates access data from any system into C1.ai's common format."

The human version has warmth and sells the benefit. The RAP version states the fact. Both are correct; they serve different audiences.

Expand Down
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# C1 documentation
# C1.ai documentation

Welcome to the official repository for [C1 documentation](https://www.conductorone.com/docs)!
Welcome to the official repository for [C1.ai documentation](https://www.conductorone.com/docs)!

We believe that great documentation is a community effort. This repository contains the source files for our docs site, and we’re excited to open it up for public contributions. Whether you've found a typo, a broken link, or have a suggestion for a new guide, we welcome your input.

Expand All @@ -20,9 +20,9 @@ If you have larger changes or want to work locally:

## 📝 Review process

Every contribution, no matter how small, helps improve the experience for all C1 users. So thank you!
Every contribution, no matter how small, helps improve the experience for all C1.ai users. So thank you!

Once you submit a pull request, the **C1 documentation team** will review your suggestions. We may ask for clarification or make minor adjustments to ensure consistency with our style guide. Once approved, we’ll merge your changes and they’ll be live on the site shortly after!
Once you submit a pull request, the **C1.ai documentation team** will review your suggestions. We may ask for clarification or make minor adjustments to ensure consistency with our style guide. Once approved, we’ll merge your changes and they’ll be live on the site shortly after!

## 🤖 Writing with Claude

Expand Down
20 changes: 10 additions & 10 deletions conductorone-api/api.mdx
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
---
title: Introducing C1's API
og:title: Introducing C1's API - C1
og:description: The C1 API can be used to access data, automate tasks, and create integrations.
description: The C1 API can be used to access data, automate tasks, and create integrations.
sidebarTitle: "C1 API and keys"
title: Introducing C1.ai's API
og:title: Introducing C1.ai's API - C1.ai
og:description: The C1.ai API can be used to access data, automate tasks, and create integrations.
description: The C1.ai API can be used to access data, automate tasks, and create integrations.
sidebarTitle: "C1.ai API and keys"
---

The C1 application programming interface (API) is a set of rules that defines how C1 can communicate with other software programs. The C1 API lets developers access C1 data and functionality, automate workflows, and connect C1 to other tools and interfaces.
The C1.ai application programming interface (API) is a set of rules that defines how C1.ai can communicate with other software programs. The C1.ai API lets developers access C1.ai data and functionality, automate workflows, and connect C1.ai to other tools and interfaces.

## Create a personal API key

Create a personal API key to use when working with the C1 API.
Create a personal API key to use when working with the C1.ai API.

<Steps>
<Step>
In the C1 web app, open your profile menu and select **API keys**.
In the C1.ai web app, open your profile menu and select **API keys**.
</Step>
<Step>
Click **Create credential**.
Expand All @@ -23,7 +23,7 @@
Give your new API key a name and select whether the key will expire.
</Step>
<Step>
**Optional.** To limit where the API key can make requests from, enter the allowed IP addresses in the **Limit source IPs** field. Specific IP addresses and CIDRs are both accepted.

Check warning on line 26 in conductorone-api/api.mdx

View check run for this annotation

Mintlify / Mintlify Validation (conductorone) - vale-spellcheck

conductorone-api/api.mdx#L26

Did you really mean 'CIDRs'?
</Step>
<Step>
Use **Limit Scopes** to select the scope of the API key. Any user can restrict a key's permissions below their own role — for example, to read-only — when creating it:
Expand All @@ -46,10 +46,10 @@

The API key is added to list of your personal API clients, and its client ID and usage data for the key are shown. If needed, you can delete the API key from this page.

## View and manage all API keys for your C1 tenant
## View and manage all API keys for your C1.ai tenant

<Warning>
Only users with the **Super Administrator** [user role](/product/admin/user-roles) in C1 can view and manage API keys other than their own.
Only users with the **Super Administrator** [user role](/product/admin/user-roles) in C1.ai can view and manage API keys other than their own.
</Warning>

<Steps>
Expand Down
Loading