## 1. Project Overview & Quickstart (steel-dev/ARCHITECTURE)

# ARCHITECTURE

Open-source repository steel-dev/ARCHITECTURE

### Repository Details
- **Repository:** [steel-dev/ARCHITECTURE](https://github.com/steel-dev/ARCHITECTURE)
- **Primary Language:** Code

*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*

## 2. Official Technical Reference & Guides (steel-dev/docs)

# Steel Docs

Documentation for Steel.dev. Built with [Fumadocs](https://fumadocs.vercel.app/) and enhanced with custom components.

## Contributing

### Documentation Structure

**Component-Based** (`/tools/*`): Features organized by tool capabilities

Example structure:

```
/tools/steel/
├── Overview/                 # Introduction and setup
├── Steel CLI/             # Command-line features
├── Steel JS SDK/          # Testing and programmatic usage
└── Integrations/             # External connections
```

### Writing Guidelines

After installing dependencies, install [Vale](https://vale.sh/docs/install), sync the pinned style
packages, and run the prose checks before submitting documentation changes:

```bash
brew install vale
bun add --global mdx2vast@0.5.0
bun run prose:sync
bun run prose
```

Vale checks MDX-aware editorial and Steel terminology rules. `cspell` remains the source of truth
for spelling and project vocabulary. During the initial rollout, Vale reports warnings without
failing the command or CI.

Follow our content rhythm pattern:

```
Paragraph (2-3 sentences) → Code Example → Paragraph → List/Table → Code
```

- **60% code, 40% text** - Show, don't just tell
- **Never put two paragraphs in a row** - Break with code/lists/tables
- **Every concept needs a code example**
- **Use complete, contextual sentences** - Explain "why" before "how"

### Available Components

#### Layout Components

````mdx
<Steps>
  <Step>
    ### Action verb phrase Context sentence explaining what and why. ```terminal
    $ command with options ```
  </Step>
</Steps>

---

<TerminalPicker storage="macOs" flags="-w">

```terminal !! macOS
$ brew install @steel-dev/cli
```

```terminal !! Windows
$ winget install @steel-dev/cli
```

</TerminalPicker>

---

<CodeTabs storage="languageSwitcher">

```typescript
const client = Steel()
const result = await client.sessions.create()
```

```javascript
const client = Steel()
const result = await client.sessions.create()
```

</CodeTabs>
````

#### Directives (Auto-converted to components)


```mdx
:::callout
type: tip|info|warn|help
### Optional Title
Content here
:::

:::objectives
- What you'll learn
- Another learning objective
:::

:::prerequisites
- Required knowledge
- Tools needed
:::

:::next-steps
- [Next Guide](/path): Description
- [Another Guide](/path): Description
:::
```


#### Interactive Components

```mdx
<Accordion>
  <AccordionItem>
    <AccordionTrigger>Question</AccordionTrigger>
    <AccordionContent>Answer</AccordionContent>
  </AccordionItem>
</Accordion>


```

#### Code Block Features

**Languages**: `terminal`, `typescript`, `javascript`, `json`, `yaml`, `console`, `package-install`

**Flags**: `-n` (line numbers), `-c` (copy button), `-w` (word wrap), `-a` (animate), `-f <file-name>` (file name)

**Annotations**:

````mdx
```ts
// !mark[3:5]     Highlight lines 3-5
// !mark[/regex/] Highlight pattern
// !diff +        Addition
// !diff -        Removal
// !collapse[3:5] Collapse lines
```
````

````

**Special blocks**:

```terminal
$ command         # Renders with prompt
```

```package-install
@steel-dev/cli  # Auto-generates npm/yarn/pnpm commands
```

````

### Page Templates

#### Overview Page

```mdx
---
title: Tool Name
sidebarTitle: Overview
---

## Overview

Expand on what the tool does and its value. Include llms.txt link if available.

## Key features

- **Feature** - User benefit description
- **Feature** - Technical capability explained simply

## Installation

<TerminalPicker>...</TerminalPicker>

:::next-steps

- [Quickstart](/path): Get started in minutes
  :::
```

use the `isLink: true` in the front matter to add a link icon to the right of the navbar icon
use the `isSeperator: true` in the frontmatter to make a doc element look like a seperator (Bold/All caps and spaced out, good for special links)

#### Quickstart Page

```mdx
---
title: Quickstart
---

Brief intro paragraph about what you'll build.

:::objectives

- Learning objective 1
- Learning objective 2
  :::

:::prerequisites

- Prerequisites
  :::

## Quickstart

<Steps>[3-5 focused steps]</Steps>

:::next-steps

- [Next Guide](/path): Description
  :::
```

### File Structure

- `/content/docs/` - All documentation content
- `/components/` - Custom components
- `/public/` - Images and static assets
- `meta.json` files control sidebar organization

### Quick Checklist

- Follow content rhythm (no consecutive paragraphs)
- 60% code, 40% text ratio
- Every concept has a code example
- Use appropriate page template
- Specify language for all code blocks
- Include context before code
- Keep paragraphs to 2-3 sentences