# Your first AI-assisted edit

> For Jenks — make a first content change with AI help, preview it on dev.jenksguo.xyz and promote it to the live site.

## Who this is for

This tutorial is for Jenks, the site's only admin. You will ask the site's model to draft a change
to one experience entry, review the diff, apply it to the **dev** branch, check the preview and then
publish it. Nothing reaches jenksguo.xyz until you promote it.

## Before you start

You need the `jenks` CLI (see [Connect your agent](/agents/docs/tutorials/connect-your-agent)) and
your admin token. The token lives in the macOS Keychain as `agent-env:JENKSGUO_ADMIN_TOKEN`. Load it
into your shell for this session only:

```bash
export JENKSGUO_ADMIN_TOKEN="$(security find-generic-password -s agent-env:JENKSGUO_ADMIN_TOKEN -w)"
```

Never paste the token into a chat, a commit or a content file.

## Step 1 — check your access

```bash
jenks admin whoami
```

You should see that the token is valid and that GitHub publishing is configured. If publishing is
not configured, edits can still be validated but not committed.

## Step 2 — read the current entry

```bash
jenks admin get xero-developer-evangelist
```

This prints the raw source: YAML frontmatter (title, dates, tags, lenses, metrics, proof) and the
Markdown body (Overview, What Jenks did, Achievements, Why it matters to employers). Read it before
you change it — you will review the AI's draft against it.

## Step 3 — ask the AI for a draft, on dev

```bash
jenks admin ai-edit xero-developer-evangelist \
  "tighten the summary to under 30 words without changing any facts" \
  --branch dev
```

The site's model rewrites the file and returns three things:

- the **proposed content**,
- a **diff** against the current file,
- **validation problems**, if any, from the same schema the build uses.

Nothing is committed yet.

## Step 4 — review the diff

Check, line by line:

- Every fact still matches what is true. The AI must not add numbers, dates or claims.
- Official job titles are unchanged.
- Tags and lenses are still valid (the validator will flag unknown ones).

If the draft is wrong, run `ai-edit` again with a clearer instruction, or edit the file yourself and
use `jenks admin put`.

## Step 5 — apply it to dev

```bash
jenks admin ai-edit xero-developer-evangelist \
  "tighten the summary to under 30 words without changing any facts" \
  --branch dev --apply
```

`--apply` validates the proposal again and commits it to the `dev` branch.

## Step 6 — watch the pipeline

```bash
jenks admin deploys
```

CI re-translates the changed entry into the six other languages, rebuilds the site and deploys the
`dev` branch. This usually takes a few minutes.

## Step 7 — check the preview

Open `https://dev.jenksguo.xyz/career/xero-developer-evangelist` and a translated version such as
`https://dev.jenksguo.xyz/zh/career/xero-developer-evangelist`. The dev site is not indexed by
search engines.

## Step 8 — publish

```bash
jenks admin promote
```

This merges `dev` into `main`; CI then deploys jenksguo.xyz.

## What you learned

- AI drafts, you decide: `ai-edit` never commits without `--apply`.
- The same validator protects the CLI, the REST API, MCP and the `/admin` console.
- Translations follow automatically, and git history keeps every version, so any change can be undone.

Next: [Update content with AI](/agents/docs/how-to/update-content-with-ai) covers multi-file changes
and the other ways to edit.