Skip to content

AGENTS.md

Latest commit

 

History

History
165 lines (112 loc) · 7.82 KB

AGENTS.md

File metadata and controls

165 lines (112 loc) · 7.82 KB
Raw

AGENTS.md

Purpose

This repository contains the Mintlify source for docs.tilebox.com. Use this file to keep documentation updates consistent with the current information architecture, writing style, and tooling.

Required Writing Skill

Always read and respect the writing-technical-content skill before writing, drafting, revising, or outlining technical documentation, guides, or long-form content in this repository.

Information Architecture

Navigation is defined in docs.json and currently follows this top-level structure:

  1. Documentation: product docs, concepts, and capability docs for Datasets, Storage, and Workflows.
  2. User Guides: task-focused walkthroughs (mostly step-by-step procedures).
  3. Languages & SDKs: language-specific install and usage docs for Python and Go.
  4. API Reference: method-level reference pages for Python and Go clients.
  5. Changelog: product updates.

When adding or moving pages:

  1. Keep docs.json in sync with actual files.
  2. Keep page paths aligned with their navigation section. If a page appears under a named group such as Agents and AI Tools, Run and Inspect, or Automations, place it under the matching slugged folder (agents-and-ai-tools/, workflows/run-and-inspect/, workflows/automations/) so the URL reflects the sidebar structure.
  3. Keep pages grouped by product area (datasets/, workflows/, sdks/, guides/, api-reference/).
  4. Keep the User Guides nav and the Tilebox Cookbook in sync. Whenever you add, remove, rename, or move a guides/** page in docs.json, update guides/cookbook.mdx with the same guide metadata, and vice versa.
  5. Preserve the current pattern where high-level landing pages link to deeper pages via Card/HeroCard blocks.

Diátaxis Mapping

We follow Diátaxis. Pick one primary intent per page and keep it focused.

  1. Tutorial: onboarding learning journeys (for example quickstart.mdx).
  2. How-to guide: concrete goals via ordered steps (primarily under guides/**).
  3. Explanation: conceptual understanding and mental models (for example datasets/concepts/**, workflows/concepts/**, introductions).
  4. Reference: factual lookup docs (primarily api-reference/**, parameter tables, changelog entries).

Practical rule: if a page starts drifting into multiple intents, split it into separate pages and cross-link them.

Writing Style And Tone

Follow the existing house style:

  1. Audience: developers and technical users integrating Tilebox.
  2. Voice: direct, clear, and pragmatic; prefer active voice and short paragraphs.
  3. Person: usually second person (you) for guidance.
  4. Tense: present tense for behavior and capabilities.
  5. Scope: explain what the reader needs now; avoid broad marketing language.

Common page flow patterns in this repo:

  1. Short context paragraph after frontmatter.
  2. Related documentation card section when useful.
  3. Step-by-step sections for procedures.
  4. Next steps links/cards at the end.

For command examples in user guides, optimize for reader copy/paste rather than fully scripted automation. Prefer direct tilebox commands and simple shell setup commands such as cd, mkdir, and export. Avoid Bash command substitution, uppercase helper variables such as RELEASE_ID or JOB_ID, jq pipelines, heredocs, and --json unless the page is explicitly about structured output or automation. When a later command needs a value returned by an earlier command, show the earlier command output and use a placeholder such as <JOB_ID> in follow-up commands.

Terminology, Capitalization, And Naming

Use consistent product language:

  1. Tilebox (capital T) everywhere.
  2. Product/module names: Tilebox Console, Tilebox Datasets, Tilebox Workflows.
  3. Generic references are lowercase: datasets, workflows, client, collection, job, task.
  4. Dataset kind names used in docs: Timeseries and Spatio-temporal.
  5. Keep acronyms uppercase (API, SDK, MCP, UUID, UTC).

Heading style in the existing docs is mostly concise sentence-style phrases (with selective title casing). Match nearby pages rather than enforcing a new global style.

MDX And Mintlify Conventions

For new non-reference pages, include frontmatter fields matching existing docs:

  1. title
  2. description
  3. icon
  4. Optional short sidebarTitle if the title is too long.

Prefer existing Mintlify components and patterns:

  1. CodeGroup for multi-language examples (usually Python first, Go second when both exist).
  2. Steps/Step for procedural flows.
  3. Tip/Note/Info/Warning for callouts.
  4. Columns + Card for internal navigation.
  5. Frame for screenshots.

Images should follow the existing light/dark pattern when both variants exist:

<img src="/path/light.png" className="dark:hidden" />
<img src="/path/dark.png" className="hidden dark:block" />

Dev Tooling

Core tooling used in this repo:

  1. Mintlify CLI for local preview and link checks.
  2. Vale for prose linting.
  3. pre-commit hook running Vale.
  4. GitHub Actions CI for Vale + broken link checks.

Local setup and validation commands:

# install tooling
npm i -g mint
vale sync
pre-commit install

# run docs locally
mint dev

# lint prose
vale .

# check broken links
mint broken-links

# optional: run all hooks
pre-commit run --all-files

CI notes:

  1. CI installs Node 24.
  2. CI installs mdx2vast before running Vale.
  3. CI runs vale sync && vale . and mintlify broken-links.

Vale expectations:

  1. Run vale . after documentation changes and make sure it passes.
  2. When writing original content, follow the active Vale rules from the start, including rules for concise language.
  3. If the user provides exact copy and it fails Vale, do not rewrite it without approval. Show the issue and ask whether to edit the copy or add an exception.
  4. If a larger rewrite is needed to satisfy Vale, or a new or updated rule creates many alerts at once, stop and ask how to proceed.

Documentation Graphics And Workflow DAG Assets

For normal documentation graphics, use the creating-documentation-graphics skill and generate PNGs with painter from the start. This applies to architecture diagrams, concept diagrams, release/deployment diagrams, data-flow diagrams, and other visual explainers embedded in docs pages.

Do not hand-author SVGs for normal documentation graphics just because they seem more maintainable. The intended output is a light/dark PNG pair, usually named like name-light.png and name-dark.png, referenced with the standard Mintlify light/dark image pattern.

The D2/SVG workflow under assets/workflows/diagrams/ is only for workflow DAG diagrams, such as task graphs, task-state DAGs, retry DAGs, optional-subtask trees, or existing diagrams with .d2 sources. When updating those workflow DAG diagrams:

  1. Edit the .d2 source.
  2. Regenerate SVG assets with python generate.py from assets/workflows/diagrams/.
  3. Commit both source and generated SVG outputs.

Update Checklist For Agents

For any substantial docs update, verify all of the following:

  1. Page intent matches a single Diátaxis category.
  2. Page is linked in docs.json in the correct section.
  3. The page path, docs.json entry, and expected public URL match the navigation group slug.
  4. If the page is under guides/**, the User Guides nav and guides/cookbook.mdx are both updated.
  5. Internal links resolve and mintlify broken-links passes.
  6. Vale warnings/errors are addressed or intentionally accepted.
  7. New screenshots/assets are optimized and use correct paths.
  8. Language and terminology match surrounding Tilebox docs.

Notes On API Reference Pages

api-reference/** pages are reference-first and should remain concise and factual. Keep examples minimal and parameter descriptions explicit. Avoid turning reference pages into long tutorials; link to guides instead.