Skip to content

Commit 494bc89

Browse files
authored
docs: restructure the docs entrypoint around user intent (anomalyco#1465)
* docs: rewrite intro with privacy-first positioning Lead with "privacy-first, open-source alternative to Claude Cowork" and cut the coding-agent framing. Reorganize the page into three scannable sections (Start / For teams / For developers), keep the existing self-host/orchestrator steps under a dedicated section below. * docs: regroup sidebar into outcome-based clusters Rename tabs "Cloud docs" → "Cloud" and "Cloud API" → "API" for shorter, clearer labels. Replace the generic "Desktop App" and "Tutorials" groups in Start here with two outcome-based clusters: "Connect your stack" (providers, MCPs, search) and "Do work with it" (browser, automations, skills, sharing). Reorganize the flat Cloud list into three clusters that map to real admin questions: "Share with your team" (templates, skill hubs, providers), "Run in the cloud" (shared workspaces, Slack), and "Manage access" (members & RBAC). Enterprise stays at the tail as a standalone contact-sales page. Slack moves from Start here to Cloud "Run in the cloud" since the Slack setup doc itself recommends pairing Slack with a remote workspace. * docs: surface changelog and roadmap on the intro Add a one-liner in the developers section pointing to the changelog and roadmap, and include both in the footer links. Developers evaluating the project want to see shipping velocity and direction. * docs(self-host): add dedicated self-host page with cloud/enterprise upsells Extract the openwork-orchestrator install steps out of the intro into a dedicated Self-host page. Keeps the intro short and gives self-hosters a direct, linkable entry point. The page includes two upsell paths: - Cloud, for readers who realize mid-read they don't want to run infra. Links into the team primitives (skill hubs, providers, RBAC, shared workspaces) that are hardest to replicate on your own box. - Enterprise, framed around concrete scale pressures (SSO, audit, allowlists, VPC, support) rather than a generic 'talk to sales' pitch. Links to the existing cloud-enterprise contact page. Add the page to the Start here tab as a top-level sibling of the intro so self-hosters find it immediately. * docs: move self-host below the outcome clusters Self-hosting is what people reach for after they've installed the desktop app and tried the basic flow, not before. Move it below "Connect your stack" and "Do work with it" so the sidebar reflects that progression. * docs: rename intro page title to "Introduction" "OpenWork" as a sidebar label is tautological — every page is about OpenWork. "Introduction" tells the reader what the page is, which is what a sidebar label is for. The in-page hero copy still carries the positioning. * docs: rewrite page titles as actions Sidebar labels should describe what the reader wants to do, not what the page is. Rename every page title to start with (or imply) a verb: - Introduction → Get started - How to connect ChatGPT to Openwork → Connect ChatGPT - How to get an Anthropic API key → Connect Anthropic - Adding a custom LLM provider/model → Connect a custom LLM - Adding a custom MCP → Add an MCP server - Enable Advanced Search with Exa → Enable Exa search - Controlling your browser with OpenWork → Control the browser - Automating Tasks → Automate tasks - Importing a skill → Import a skill - How to share your agents with others → Share your setup - Self-host OpenWork → Self-host - Missing Documentation? → Report missing docs Makes the sidebar scannable by intent: each label is a thing the reader is trying to accomplish. * docs: restore precision in provider titles "Connect X" flattened two different setup flows into one label. Readers scanning the sidebar need to know what they'll do before clicking: - Sign in with ChatGPT (OAuth, no key needed) - Add Anthropic API key (paste a secret from Anthropic) - Add a custom LLM (config, not auth) MCP and Exa labels already carry their own distinct verbs and are left unchanged. * docs: turn missing-docs into a question with two paths "Missing docs?" as a question invites the click. Inside, offer both the low-effort path (email us) and the contributor path (open a PR against the docs folder). Drops the "A message from the Openwork Developers" preamble, which was noise. * docs: reorganize into tab folders, rename files to match titles Mirrors the tab/group structure in docs.json so files are easier to locate. Filenames now track page titles (prefixes like how-to- and cloud- dropped since folders provide that context). Single-page groups stay flat at the tab root; roadmap and changelog remain at repo root as their own tabs. Cross-links in mdx files and docs.json redirects updated for the new paths. * docs: add roadmap/changelog folders, rename images, deprecate unused assets Moves roadmap.mdx and changelog.mdx into their own tab folders for consistency with the rest of the reorg, and removes the orphaned introduction.mdx. Renames CleanShot/Screenshot/image-* files to descriptive names based on content and updates the corresponding alt text. Unused images and a stray .mov land in images/deprecated/ rather than being deleted. docs.json gains /roadmap and /changelog redirects so old inbound URLs still resolve. * more clear get starter docs * docs: render get-started paths as Mintlify cards * no need to have the same title twice * edits * more concise
1 parent a6bbedc commit 494bc89

44 files changed

Lines changed: 198 additions & 140 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -183,7 +183,7 @@ title: "Changelog"
183183
- Shared skills can now be imported into existing workers.
184184
- ChatGPT Oath added to "New chat Session"
185185

186-
<img src="/images/chatgptOauth.png" alt="ChatGPT Oauth" />
186+
<img src="/images/chatgpt-new-session-cta.png" alt="New session with Connect ChatGPT for free CTA" />
187187

188188
</Update>
189189

File renamed without changes.
Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ The selected org controls which `Cloud workers`, `Team templates`, `Org skills`,
3333

3434
## What to do next
3535

36-
- Use [Skill hubs](/cloud-skill-hubs) to publish grouped skills for teams, or save a single skill directly from the desktop app and install it from `Skills -> Cloud`.
37-
- Use [Shared workspaces](/cloud-shared-workspaces) to deploy hosted OpenWork runtimes that teammates can open from the desktop app.
38-
- Use [LLM providers](/cloud-llm-providers) or [custom LLM providers](/cloud-custom-llm-providers) to manage shared model access.
39-
- Use [Members and RBAC](/cloud-members-and-rbac) to invite people, create teams, and control access.
36+
- Use [Skill hubs](/cloud/share-with-your-team/skill-hubs) to publish grouped skills for teams, or save a single skill directly from the desktop app and install it from `Skills -> Cloud`.
37+
- Use [Shared workspaces](/cloud/run-in-the-cloud/shared-workspace) to deploy hosted OpenWork runtimes that teammates can open from the desktop app.
38+
- Use [LLM providers](/cloud/share-with-your-team/managed-llm-provider) or [custom LLM providers](/cloud/share-with-your-team/custom-llm-provider) to manage shared model access.
39+
- Use [Members and RBAC](/cloud/members-and-rbac) to invite people, create teams, and control access.

packages/docs/accessing-ow-from-slack.mdx renamed to packages/docs/cloud/run-in-the-cloud/connect-slack.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ This is one of the most relevant and meaningful applications of Openwork, and we
1313

1414
> **Disclaimer:** We recommend setting the slackbot with a remote workspace instead of in your local machine to ensure there's `hardware isolation` between the remote workspace the ai can access and your local machine.
1515
16-
For team-owned Slack or other long-running connectors, you can host the runtime in an OpenWork Cloud [shared workspace](/cloud-shared-workspaces) instead of keeping it on a laptop or self-managed server.
16+
For team-owned Slack or other long-running connectors, you can host the runtime in an OpenWork Cloud [shared workspace](/cloud/run-in-the-cloud/shared-workspace) instead of keeping it on a laptop or self-managed server.
1717

1818
## Having the right slack permissions
1919

@@ -42,7 +42,7 @@ Go to [Create new app](https://api.slack.com/apps?new_app=1) in Slack. What you
4242
Now, once you have both of these tokens, you can directly paste them into the app.
4343

4444
<Frame>
45-
![Clean Shot 2026 03 24 At 17 15 15@2x](/images/CleanShot2026-03-24at17.15.15@2x.png)
45+
![Slack messaging settings with bot and app token fields](/images/slack-connect-tokens.png)
4646

4747
Paste you `xorb-` and `xapp-` tokens into `Settings` \> `messaging`
4848
</Frame>
@@ -52,7 +52,7 @@ Now, once you have both of these tokens, you can directly paste them into the ap
5252
Test the bot by sending a message. It should respond instantly indicating that a new session has been initiatied and then send the actual response afterwards. For now, you will have to use `@slack-bot-name` every time you want to talk to it.
5353

5454
<Frame>
55-
![Clean Shot 2026 03 24 At 17 16 43@2x](/images/CleanShot2026-03-24at17.16.43@2x.png)
55+
![Slack thread showing the bot reply to a test message](/images/slack-test-message-thread.png)
5656
</Frame>
5757

5858
## Template Manifest Example

packages/docs/cloud-shared-workspaces.mdx renamed to packages/docs/cloud/run-in-the-cloud/shared-workspace.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,4 +32,4 @@ Use a shared workspace when your team needs a hosted OpenWork runtime, a stable
3232
- This area is currently marked `Alpha` in the Cloud dashboard.
3333
- A workspace must be `Ready` before the desktop app can open it.
3434
- OpenWork Cloud plan limits apply to hosted workspaces.
35-
- If you prefer to self-host, the desktop [Get Started](/get-started) guide still works with `openwork-orchestrator`.
35+
- If you prefer to self-host, the desktop [Get Started](/start-here/get-started) guide still works with `openwork-orchestrator`.

packages/docs/cloud-custom-llm-providers.mdx renamed to packages/docs/cloud/share-with-your-team/custom-llm-provider.mdx

File renamed without changes.

packages/docs/cloud-llm-providers.mdx renamed to packages/docs/cloud/share-with-your-team/managed-llm-provider.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,4 +37,4 @@ OpenWork writes the imported provider into the workspace `opencode.jsonc` and st
3737
- If the provider was deleted in Cloud, the desktop app shows `Removed from cloud` and lets you `Uninstall` the local config.
3838
- The provider must have a stored org credential before the desktop app can import it.
3939

40-
If you only need a one-off local setup, use the desktop guide at [Adding a custom LLM provider/model](/how-to-connect-a-custom-provider).
40+
If you only need a one-off local setup, use the desktop guide at [Adding a custom LLM provider/model](/start-here/connect-your-stack/add-a-custom-llm).

packages/docs/cloud-skill-hubs.mdx renamed to packages/docs/cloud/share-with-your-team/skill-hubs.mdx

File renamed without changes.

packages/docs/team-provisioning.mdx renamed to packages/docs/cloud/share-with-your-team/team-templates.mdx

File renamed without changes.

0 commit comments

Comments
 (0)