Skip to content

docs(guides): add AI tooling context page - #30

Merged
ThetaSinner merged 1 commit into
mainfrom
docs/ai-tooling-context
Jul 20, 2026
Merged

docs(guides): add AI tooling context page#30
ThetaSinner merged 1 commit into
mainfrom
docs/ai-tooling-context

Conversation

@synchwire

Copy link
Copy Markdown
Collaborator

New Guides page: AI tooling context — how to fetch and use the context bundle Ordo ships for AI coding assistants.

  • Branded one-liner: curl -fsSL https://getordo.dev/ai-context.tar.gz | tar xz
  • Explains the two roles (module-author, operator) and how to drop AGENTS.md/CLAUDE.md into a project
  • Notes the bundle links the live schema + CLI reference (stays current)

Builds clean locally (/guides/ai-tooling-context/).

⚠️ Draft — gated on the branded URL going live

The page's getordo.dev/ai-context.tar.gz one-liner only works after the delivery chain lands:

  1. ordo#169 (stable-named artifact) merged + released → dl.getordo.dev/ai-context.tar.gz exists
  2. ordo-website#30 (redirect) merged → getordo.dev/ai-context.tar.gz resolves

Merge this after both. Verify:

curl -fsSL https://getordo.dev/ai-context.tar.gz | tar tz | head

@netlify

netlify Bot commented Jul 15, 2026

Copy link
Copy Markdown

Deploy Preview for ordo-docs ready!

Name Link
🔨 Latest commit 2dbaf9c
🔍 Latest deploy log https://app.netlify.com/projects/ordo-docs/deploys/6a5e96151d92250008134bb4
😎 Deploy Preview https://deploy-preview-30--ordo-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@synchwire
synchwire marked this pull request as ready for review July 20, 2026 21:15
@ThetaSinner
ThetaSinner force-pushed the docs/ai-tooling-context branch from 1b71c17 to d4a696b Compare July 20, 2026 21:17
Comment thread src/content/docs/guides/ai-tooling-context.mdx Outdated
Comment thread src/content/docs/guides/ai-tooling-context.mdx Outdated
@synchwire

Copy link
Copy Markdown
Collaborator Author

Follow-up on the version-pinning advice I added for the second review comment — it overpromised, so I have corrected it here and fixed the underlying cause upstream.

The problem: the bundle is versioned, but the schema/CLI/API pages it links are published for the latest release only (there are no per-release docs URLs — I checked, /v0.0.13/reference/cli/ is a 404). So pinning a bundle to an older Ordo gave version-matched prose with a forward-dated reference, silently — and the reference is the part the context treats as authoritative.

On this page:

  • Reframed Keep it current: running current Ordo and re-fetching is the recommended path, since it is the only combination where everything matches. Pinning is now a subsection for when you cannot upgrade, with a :::caution stating that it only matches the written guidance.
  • Noted that each bundle names the release it was generated for, so you can tell what a project is carrying.
  • Fixed a broken link: the page pointed at /reference/cli/, which 404s — the docs site publishes no index for that directory. Now /reference/.

Upstream (ordo#170): the bundle now stamps the release it was generated for, states the latest-reference caveat itself, and its broken links are repaired — the same /reference/cli/ 404 appeared in the generated links section and three prose fragments, plus a getordo.dev/schemas/ 404. All 13 links emitted into both roles now return 200.

Pushed as a fixup on the page commit; build is clean.

@synchwire

Copy link
Copy Markdown
Collaborator Author

Added a Set it up in one step section at the top: a copy-able prompt that hands the assistant this page and lets it do the install.

The prompt tells it to read the page, pick the role (module-author vs operator, ask if unclear), not overwrite an existing AGENTS.md/CLAUDE.md — merge as the page describes — and report back what it changed. Everything below it is the same process by hand.

Starlight's code blocks carry a copy button by default, so no new component was needed. Verified in the built output rather than assumed: the block renders with a copy button, its payload is the full prompt, and the line breaks survive the copy (11 line separators in the encoded payload), so pasting gives a properly formatted multi-line prompt rather than one run-on line.

Pushed as a fixup; build clean.

Document how to fetch and use the AI context bundle Ordo ships: the
branded curl one-liner, the two role directories (module-author,
operator), and how to drop AGENTS.md/CLAUDE.md into a project. Notes that
the bundle links the live schema and CLI reference rather than copying
them.
@synchwire
synchwire force-pushed the docs/ai-tooling-context branch from a60c7cd to 2dbaf9c Compare July 20, 2026 21:41
@ThetaSinner
ThetaSinner merged commit a25a6e1 into main Jul 20, 2026
5 checks passed
@ThetaSinner
ThetaSinner deleted the docs/ai-tooling-context branch July 20, 2026 21:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants