docs: restructure and improve documentation site by ppradnesh · Pull Request #137 · AltimateAI/altimate-code

ppradnesh · 2026-03-14T19:21:54Z

Summary

Major documentation restructuring for the Altimate Code docs site:

New nav structure: Getting Started (Overview + Quickstart) → Examples (Showcase + Guides) → Configure (unified section with Agents, Tools, Skills, Commands, Providers, Governance, Appearance, Integrations) → Interfaces (TUI, CLI, IDE, GitHub, GitLab) → Reference (What's New, Security FAQ, Network, Troubleshooting, Telemetry)
Merged Components + Configure into a single "Configure" section with a new overview page featuring architecture diagram and grid cards
Rewrote index.md with GTM messaging, hero section, feature cards, tool showcase, benchmarks, and quick demo prompts
Added LLM provider config to Quickstart page with /connect command and sample Anthropic config
Deduplicated content: removed duplicate example cards, trimmed warehouse/LLM config examples in Quickstart, consolidated permission docs with cross-references
Standardized terminology: "altimate" → "Altimate Code" in prose, consistent 55+ tool count across all pages, page titles matching nav labels
Added new pages: Configure overview (configure/index.md), What's New changelog (changelog.md)
Moved sections: Telemetry → Reference, Guides → Examples, Behavior → Governance
CSS improvements: site title highlight, install command no-wrap fix

Test plan

Run mkdocs serve and verify all pages render without errors
Check all internal links resolve correctly (no broken cross-references)
Verify nav structure matches expected hierarchy
Confirm "Altimate Code" appears correctly in header and browser tab
Review index.md landing page layout and formatting

🤖 Generated with Claude Code

- publish.ts: change glob from `*/package.json` to `**/package.json` to find scoped package directories (@altimate/cli-*) which are 2 levels deep - release.yml: add skip-existing to PyPI publish so it doesn't fail when the engine version hasn't changed between releases Co-authored-by: Claude Opus 4.6 <[email protected]>

Co-Authored-By: Claude Opus 4.6 <[email protected]>

…(#15780)

…ider (#15619)

@Altimate

The npm org is @AltimateAI, not @Altimate. Update all package names, workspace dependencies, imports, and documentation to use the correct scope so npm publish succeeds. Name mapping: - @altimate/cli → @altimateai/altimate-code - @altimate/cli-sdk → @altimateai/altimate-code-sdk - @altimate/cli-plugin → @altimateai/altimate-code-plugin - @altimate/cli-util → @altimateai/altimate-code-util - @altimate/cli-script → @altimateai/altimate-code-script Also updates publish.ts to emit the wrapper package as @altimateai/altimate-code (no -ai suffix) and hardcodes the bin entry to altimate-code. Co-authored-by: Claude Opus 4.6 <[email protected]>

Two issues: 1. TypeScript permission-task tests: test fixture wrote config to `opencode.json` but the config loader only looks for `altimate-code.json`. Updated fixture to use correct filename. 2. Python tests: `pytest: command not found` because pyproject.toml had no `dev` optional dependency group. Added `dev` extras with pytest and ruff. Co-authored-by: Claude Opus 4.6 <[email protected]>

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: rename opencode references to altimate-code in all test files Update test files to use the correct names after the config loader was renamed from opencode to altimate-code: - `opencode.json` → `altimate-code.json` - `.opencode/` → `.altimate-code/` - `.git/opencode` → `.git/altimate-code` - `OPENCODE_*` env vars → `ALTIMATE_CLI_*` - Cache dir `opencode` → `altimate-code` - Schema URL `opencode.ai` → `altimate-code.dev` Co-Authored-By: Claude Opus 4.6 <[email protected]> * fix: resolve remaining test failures and build import issue - Fix build.ts solid-plugin import to use bare specifier for monorepo hoisting - Update agent tests: "build" → "builder", "plan" → "analyst" for disabled fallback - Fix well-known config mock URL in config.test.ts - Fix message-v2 test: "OpenCode" → "Altimate CLI" - Fix retry.test.ts: replace unsupported test.concurrent with test - Fix read.test.ts: update agent name to "builder" - Fix agent-color.test.ts: update config keys to "builder" - Fix registry.test.ts: remove unpublished plugin dep from test fixture - Skip adding plugin dependency in local dev mode (installDependencies) Co-Authored-By: Claude Opus 4.6 <[email protected]> * fix: address Sentry review comments and Python CI deps - Update theme schema URL from opencode.ai to altimate-code.dev (33 files) - Rename opencode references in ACP README.md and AGENTS.md docs - Update test fixture tmp dir prefix to altimate-code-test- - Install warehouse extras in Python CI for duckdb/boto3 test deps Co-Authored-By: Claude Opus 4.6 <[email protected]> * fix: Python CI — SqlGuardResult allows None data, restrict pytest to tests/ - Allow SqlGuardResult.data to be None (fixes lineage.check Pydantic error) - Set testpaths = ["tests"] in pyproject.toml to exclude src/test_local.py from pytest collection (it's a source module, not a test) Co-Authored-By: Claude Opus 4.6 <[email protected]> * fix: resolve ruff lint errors in Python engine - Remove unused imports in server.py (duplicate imports, unused models) - Remove unused `json` import in schema/cache.py - Remove unused `os` import in sql/feedback_store.py - Add noqa for keyring availability check import Co-Authored-By: Claude Opus 4.6 <[email protected]> --------- Co-authored-by: Claude Opus 4.6 <[email protected]>

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Use import.meta.resolve to find the @opentui/core package directory instead of hardcoding node_modules path, which fails with monorepo hoisting. Co-Authored-By: Claude Opus 4.6 <[email protected]>

…aming - Build: output binary as altimate-code instead of opencode - Bin wrapper: look for @altimateai/altimate-code-* scoped packages - Postinstall: resolve @AltimateAI scoped platform packages - Publish: update Docker/AUR/Homebrew refs to AltimateAI/altimate-code - Publish: make Docker/AUR/Homebrew non-fatal (infra not set up yet) - Dockerfile: update binary paths and names Co-Authored-By: Claude Opus 4.6 <[email protected]>

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Co-authored-by: Jérôme Benoit <[email protected]>

…sion (#15762) Co-authored-by: Test User <[email protected]> Co-authored-by: Shoubhit Dash <[email protected]>

Co-authored-by: Adam <[email protected]>

Reorganize docs into Home, Setup, Examples, Components, Configure, and Reference sections. Add 6 example pages from Datamates docs. Rewrite index page with updated GTM messaging. Remove Develop section. Co-Authored-By: Claude Opus 4.6 <[email protected]>

Add "What you can do today" section with 7 example prompts. Expand LLM providers from 9 to 17 (add Vertex AI, DeepInfra, Cerebras, Cohere, Together AI, Perplexity, xAI, GitHub Copilot). Co-Authored-By: Claude Opus 4.6 <[email protected]>

… examples - Merge Components and Configure into unified Configure section with new overview page - Rename Usage to Interfaces, remove Web page - Add Getting Started section with Overview and Quickstart sub-pages - Add LLM provider configuration examples to Quickstart (Anthropic, OpenAI, Bedrock) - Add "See it in action" examples section to index page - Remove individual example pages, keep Showcase linking to Datamates docs - Remove "Using with Claude Code" and "Using with Codex" sections - Update site name to "Altimate Code" with highlighted header styling - CSS: site title highlight, text-transform override Co-Authored-By: Claude Opus 4.6 <[email protected]>

- Remove duplicate example cards from index.md (keep in examples/index.md) - Trim warehouse and LLM config examples in quickstart, link to full references - Consolidate permission docs into permissions.md with cross-refs from agents, tools, security FAQ - Fix footer Learn More links to match current nav labels - Standardize tool count to 55+ across all pages - Standardize terminology: "altimate" → "Altimate Code" in prose - Update configure overview: "Behavior" → "Governance", add inline links - Add Config File Reference to Configure nav - Move Tool Config/Custom Tools to top of Tools sub-section - Add What's New changelog page under Reference - Move Telemetry to Reference, Guides to Examples - Add inline links to architecture paragraph in configure overview - Standardize page titles to match nav labels (Quickstart, Showcase, Config File Reference) Co-Authored-By: Claude Opus 4.6 <[email protected]>

github-actions · 2026-03-14T19:22:07Z

This PR doesn't fully meet our contributing guidelines and PR template.

What needs to be fixed:

PR description is missing required template sections. Please use the PR template.

Please edit this PR description to address the above within 2 hours, or it will be automatically closed.

If you believe this was flagged incorrectly, please let a maintainer know.

github-actions · 2026-03-14T21:39:06Z

This pull request has been automatically closed because it was not updated to meet our contributing guidelines within the 2-hour window.

Feel free to open a new pull request that follows our guidelines.

Move .md files into directories matching the five nav sections: getting-started/, examples/, configure/, interfaces/, reference/. Eliminates data-engineering/ dir and renames usage/ to interfaces/. Co-Authored-By: Claude Opus 4.6 <[email protected]>

sentry · 2026-03-15T15:01:02Z

docs/mkdocs.yml

+      - Config File Reference: configure/config.md
+      - Agents:
+          - Agent Modes: configure/agent-modes.md


Bug: Several documentation pages, including two guides and the web interface page, are missing from the mkdocs.yml navigation configuration, making them inaccessible to users.
_{Severity: MEDIUM}

Suggested Fix

Update the nav section in docs/mkdocs.yml. Add 'examples/guides/using-with-claude-code.md' and 'examples/guides/using-with-codex.md' to the 'Guides' list. Add 'interfaces/web.md' to the 'Interfaces' list to ensure all pages are correctly linked in the site navigation.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not valid. Location: docs/mkdocs.yml#L65-L67 Potential issue: During a documentation restructure, several files were moved but their corresponding entries in the `mkdocs.yml` navigation configuration were not updated. Specifically, `using-with-claude-code.md` and `using-with-codex.md` are missing from the 'Guides' section, and `interfaces/web.md` is missing from the 'Interfaces' section. As a result, these pages will be rendered on the documentation site but will be orphaned, meaning they will not appear in any navigation menus and will be inaccessible to users browsing the site unless they have a direct URL.

_{Did we get this right? 👍 / 👎 to inform future reviews.}

Update relative paths for images and cross-references across 7 files to reflect the new directory layout. Co-Authored-By: Claude Opus 4.6 <[email protected]>

sentry · 2026-03-15T15:05:46Z

docs/docs/reference/security-faq.md

-  }
-}
-```
+By default, destructive operations like `bash`, `write`, and `edit` require confirmation. You can restrict specific commands, deny destructive SQL (DROP, DELETE, TRUNCATE), and configure per-agent permissions. See the [Permissions reference](configure/permissions.md) for full examples.


Bug: Relative links in security-faq.md and configure/tools/config.md are broken due to a directory restructure, as the link paths were not updated.
_{Severity: MEDIUM}

Suggested Fix

Update the relative links in the affected files. In docs/docs/reference/security-faq.md, change links from configure/permissions.md to ../configure/permissions.md. In docs/docs/configure/tools/config.md, change links from permissions.md to ../permissions.md to correctly point to the file from the new, deeper directory.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not valid. Location: docs/docs/reference/security-faq.md#L30 Potential issue: After a directory restructure, relative links in two documentation files were not updated, causing them to break. In `docs/docs/reference/security-faq.md`, links like `configure/permissions.md` are now incorrect because the file was moved one level deeper. Similarly, in `docs/docs/configure/tools/config.md`, links to `permissions.md` are broken because the file was moved into the `tools/` subdirectory. These broken links will lead to 404 errors for users navigating the documentation site.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Move Overview to top, Custom Tools to bottom, and add Built-in Tools row to the tools overview table. Co-Authored-By: Claude Opus 4.6 <[email protected]>

…ix broken links - Split Configure into Use (agents, tools, skills, commands, interfaces) and Configure (config file, warehouses, LLMs, MCPs/ACPs, appearance) - Move Governance (rules, permissions, context, formatters) to its own section - Move Interfaces under Use as a sub-section - Add new Warehouses page with connection examples for all 8 warehouse types - Fix broken internal links across multiple pages Co-Authored-By: Claude Opus 4.6 <[email protected]>

- Add Core Tools page documenting 28 altimate_core_* Rust engine tools - Add dbt_lineage and dbt_profiles to dbt tools page (was 2, now 4) - Document all 11 built-in skills (was 5 documented) - Add Executive agent mode (was missing from docs) - Fix agent mode count from "four" to "five" - Update tool count from 55+ to 70+ across all pages - Add Core Tools to nav Co-Authored-By: Claude Opus 4.6 <[email protected]>

Added 4 missing subcommands (attach, db, debug, completion), expanded descriptions with sub-commands, and added 7 missing global flags (--continue, --session, --fork, --prompt, --port, --hostname, --mdns, --cors). Co-Authored-By: Claude Opus 4.6 <[email protected]>

Added governance overview page explaining why governance makes agents better (not just safer), with summaries linking to rules, permissions, context management, and formatters. Moved Config File Reference to last item under Configure section. Co-Authored-By: Claude Opus 4.6 <[email protected]>

Co-Authored-By: Claude Opus 4.6 <[email protected]>

…overview page Merged the two sections into one, moved it above Benchmarks, and added PySpark migration and Airflow debugging example prompts. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

dev-punia-altimate · 2026-03-17T14:21:53Z

✅ Tests — All Passed

TypeScript — passed

Python — passed

_{Tested at ffcfeaf2 | Run log | Powered by QA Autopilot}

anandgupta42 and others added 30 commits March 2, 2026 19:45

release: v0.1.7

0a08668

Co-Authored-By: Claude Opus 4.6 <[email protected]>

fix(opencode): clone part data in Bus event to preserve token values …

fd6f713

…(#15780)

fix(provider): forward metadata options to cloudflare-ai-gateway prov…

96d6fb7

…ider (#15619)

chore: generate

e41b535

release: v0.1.8

dc61802

Co-Authored-By: Claude Opus 4.6 <[email protected]>

fix(opencode): avoid gemini combiner schema sibling injection (#15318)

7e3e85b

chore: generate

9f150b0

release: v0.1.9

614c180

Co-Authored-By: Claude Opus 4.6 <[email protected]>

fix: resolve @opentui/core parser.worker.js via import.meta.resolve

8738470

Use import.meta.resolve to find the @opentui/core package directory instead of hardcoding node_modules path, which fails with monorepo hoisting. Co-Authored-By: Claude Opus 4.6 <[email protected]>

wip: zen

6aa4928

chore: generate

881ca86

wip: zen

1233ebc

wip: zen

b985ea3

zen: docs

6deb27e

release: v0.1.10

391f365

Co-Authored-By: Claude Opus 4.6 <[email protected]>

chore: nix flake update for bun 1.3.10 (#15648)

48412f7

Co-authored-by: Jérôme Benoit <[email protected]>

fix(opencode): disable session navigation commands when no parent ses…

18850c4

…sion (#15762) Co-authored-by: Test User <[email protected]> Co-authored-by: Shoubhit Dash <[email protected]>

fix(app): timeline jank

5e8742f

fix(app): timeline jank

e4af1bb

chore: fix test

1e2da60

chore: cleanup

7305fc0

fix(app): stabilize project close navigation (#15817)

356b5d4

Co-authored-by: Adam <[email protected]>

fix: update Turkish translations (#15835)

cbf0570

chore: generate

70b6a05

chore: tr glossary

da82d40

ppradnesh and others added 4 commits March 13, 2026 18:31

github-actions bot added the needs:compliance label Mar 14, 2026

ppradnesh requested a review from anandgupta42 March 14, 2026 19:22

github-actions bot removed the needs:compliance label Mar 14, 2026

github-actions bot closed this Mar 14, 2026

anandgupta42 reopened this Mar 15, 2026

ppradnesh had a problem deploying to github-pages March 15, 2026 01:48 — with GitHub Actions Failure

github-actions bot added the needs:compliance label Mar 15, 2026

sentry bot reviewed Mar 15, 2026

View reviewed changes

docs: fix broken internal links after directory restructure

98004b4

Update relative paths for images and cross-references across 7 files to reflect the new directory layout. Co-Authored-By: Claude Opus 4.6 <[email protected]>

sentry bot reviewed Mar 15, 2026

View reviewed changes

ppradnesh and others added 9 commits March 15, 2026 08:08

docs: update governance descriptions on overview and configure pages

1093c92

Co-Authored-By: Claude Opus 4.6 <[email protected]>

docs: remove redundant architecture diagram from configure overview

8efa64e

Co-Authored-By: Claude Opus 4.6 <[email protected]>

docs: rename Tool Config to Built-in Tools, reorder tools nav

94e4912

Move Overview to top, Custom Tools to bottom, and add Built-in Tools row to the tools overview table. Co-Authored-By: Claude Opus 4.6 <[email protected]>

docs: update IDE page with Datamates extension info, mark as WIP

0197624

Co-Authored-By: Claude Opus 4.6 <[email protected]>

docs: combine See it in action and What you can do today sections on …

ffcfeaf

…overview page Merged the two sections into one, moved it above Benchmarks, and added PySpark migration and Airflow debugging example prompts. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

anandgupta42 force-pushed the main branch from c86970e to d097682 Compare March 17, 2026 00:40

arora-saurabh448 closed this Mar 19, 2026

arora-saurabh448 deleted the docs-branch branch March 19, 2026 06:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: restructure and improve documentation site#137

docs: restructure and improve documentation site#137
ppradnesh wants to merge 10000 commits intomainfrom
docs-branch

ppradnesh commented Mar 14, 2026

Uh oh!

github-actions bot commented Mar 14, 2026

Uh oh!

github-actions bot commented Mar 14, 2026

Uh oh!

sentry bot Mar 15, 2026

Uh oh!

sentry bot Mar 15, 2026

Uh oh!

dev-punia-altimate commented Mar 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

20 participants

Conversation

ppradnesh commented Mar 14, 2026

Summary

Test plan

Uh oh!

github-actions bot commented Mar 14, 2026

Uh oh!

github-actions bot commented Mar 14, 2026

Uh oh!

sentry bot Mar 15, 2026

Choose a reason for hiding this comment

Uh oh!

sentry bot Mar 15, 2026

Choose a reason for hiding this comment

Uh oh!

dev-punia-altimate commented Mar 17, 2026

✅ Tests — All Passed

TypeScript — passed

Python — passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

20 participants