# KeyFlow CLI Guide for AI Agents

Use this when a person asks you to post, upload, or publish something to KeyFlow (키플로우).
It works the same for any agent that can run shell commands.

## 1. Steps

1. Write one Markdown file (for example `post.md`). Use the frontmatter and syntax below.
2. Run `keyflow check post.md --json` and fix every error.
3. Ask the person before uploading. Say whether it will be a private draft or a public post.
4. Run `keyflow push post.md`. Report the returned post ID and URL.
5. To change the post later, edit the same file and run `keyflow push post.md` again. It updates the same post.

If `keyflow` is not logged in, ask the person to run `keyflow login` themselves.

## 2. Frontmatter (all optional)

```yaml
---
title: Post title          # default: the first "# heading"
tags: [nextjs, cache]
publish: false             # true = publish (needs the person's approval)
visibility: public         # public | followers | private
cover: ./images/cover.png  # local path or https URL
summary: One-line summary  # default: KeyFlow writes an AI summary
language: ko               # ko | en, default: detected
---
```

- No `publish` means a private draft.
- `publish: true` without `visibility` publishes as `public`.
- The CLI adds a `keyflow:` block with the post ID after the first upload. Do not edit or remove it unless the person wants a new post.
- If you do not set `title`, the first `# heading` becomes the title and is not repeated in the body.

## 3. Images

- Use local paths as normal Markdown images: `![Architecture diagram](./images/diagram.png)`.
- Paths are relative to the Markdown file. The CLI uploads them and rewrites the uploaded copy only.
- Allowed: PNG, JPEG, WebP, GIF. Max 10 MB each, 50 per post. SVG is not accepted.
- Always write alt text in the brackets.

## 4. KeyFlow syntax

### Callouts

```markdown
> [!TIP]
> Shorter builds come from caching the dependency layer.
```

Types: `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`, `AI`, `USER`, `BOT`, `STEP`.
Use `USER` and `BOT` for a question and answer, and `STEP` for numbered tutorial steps.

### Code

Always name the language after the opening fence:

````markdown
```ts
export const answer = 42;
```
````

### Math

Inline: `$E = mc^2$`. Block:

```markdown
$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$
```

### Link card

```html
<link-card url="https://example.com/article" title="Article title" description="One sentence" image="https://example.com/og.png"></link-card>
```

### Document card

```html
<document-card url="https://example.com/spec.pdf" title="Spec" date="2026-09-24"></document-card>
```

### Runnable code (Sandpack)

````markdown
```sandpack
{"template":"react","files":{"/App.js":"export default function App() { return <h1>Hi</h1>; }"}}
```
````

## 5. Common mistakes

- A `#word` after a space or at the start of a line becomes a tag link. Write `\#word` or put it in backticks if you do not want a tag.
- Do not start the body with the same heading as `title`.
- Scripts and inline event handlers are removed when the post is rendered.
- Do not invent new callout types. Unknown types fail `keyflow check`.

## 6. Rules

- Never ask for, print, log, or store KeyFlow credentials, tokens, or `.env` values.
- Get the person's approval before `publish: true` or `--publish`.
- Do not claim a post is published unless `keyflow push` reported it.