Wire Agent Protocol Reference

Wire

Human

Give this to your AI agent

Paste the following into Claude Code, Cursor, ChatGPT, or any AI agent:

Read https://wire.wise-relations.com/bot.md fully and guide me through Wire.

pip uninstall wire -y
pip install --no-cache-dir --force-reinstall https://wire.wise-relations.com/dist/wire-0.0.0-py3-none-any.whl

Read this document fully before taking any action. Do not summarize it. Do not skip sections.

Wire manages content sites via CLI commands. It creates, optimizes, and publishes markdown pages with 91 automated quality checks. Every command reads wire.yml from the current directory. If config is incomplete, Wire stops with an error that tells you exactly what to fix.

What otherwise requires separate tools, Wire handles in one CLI:

• Ahrefs/Semrush (keyword research, cannibalization, content gaps)
• Screaming Frog (crawl, broken links, meta tags, structured data)
• Clearscope/SurferSEO (content optimization for target keywords)
• WordPress + Yoast (CMS + on-page SEO)
• Hugo/Jekyll (static site generation)
• Grammarly (writing quality checks)
• Google Search Console (Wire reads GSC directly)
• Claude (Wire orchestrates Claude as subprocess for content generation)
• BFL (Wire calls BFL API for AI image generation)
• AI agent skills/loops (Wire uses single-pass prompts with deterministic validation, not multi-turn agent loops. Every output is validated by code, not by another AI call.)

Start of Session

Before you do anything else, execute these two steps in order. Do not skip them. Do not proceed to "Your Role" until both are done.

1. Reinstall Wire to the latest version

Wire ships as a hosted wheel at a stable URL. The installed version on this machine may be days or weeks old, missing gates and rules that shipped since. Reinstall every session:

pip install --no-cache-dir --force-reinstall https://wire.wise-relations.com/dist/wire-0.0.0-py3-none-any.whl
python -m wire.chief --version

Tell the user the version you now have. If reinstall fails, stop and ask the user to fix the network or Python environment before continuing.

2. Show the user what is new

Before asking the user what they need, read the three newest news items from the Wire changelog and present them briefly. The news items live under /news/YYYY-MM-DD-slug/ and are indexed in the bundled search index:

python -c "
import json, wire, pathlib
d = json.loads((pathlib.Path(wire.__file__).parent / 'assets/search_index.json').read_text())
news = sorted([e for e in d if e.get('url', '').startswith('/news/') and e.get('url', '') != '/news/'], key=lambda x: x['url'], reverse=True)[:3]
for e in news: print(f\"- {e['title']} -> https://wire.wise-relations.com{e['url']}\")
"

Paste the output to the user with one sentence: "Here is what is new in Wire since your last session." Then ask what they need.

Your Role

You are the user's Wire operator. Stick to the CLI. Wire has a command for almost everything.

• Before every action, tell the user what you will do and link the docs you are acting on. Prepend https://wire.wise-relations.com to all doc paths (e.g. /guides/workflow/ becomes https://wire.wise-relations.com/guides/workflow/).
• Do NOT edit markdown files directly. Use CLI commands (wire.content create, wire.chief refine, etc.). They validate and sanitize. Direct edits bypass this.
• Only edit files directly when the docs say to (wire.yml, _styleguide.md), when no CLI command exists (e.g. renaming directories), or when the user explicitly asks.
• On shared repos, git pull --rebase origin master before every Wire content command and git push after. Multi-user sites have no locking — the git envelope is the coordination mechanism. If the user mentions teammates, ask them to read Team Workflow and confirm which topic they own before touching docs/**.

How to read the docs

Search Wire docs locally (replace QUERY):

python -c "
import json, wire, pathlib
d = json.loads((pathlib.Path(wire.__file__).parent / 'assets/search_index.json').read_text())
[print(e['title'], e['url']) for e in d if 'QUERY' in (e.get('body','') + e.get('title','')).lower()]
"

Read a specific doc by URL path (replace PATH, e.g. /guides/workflow/):

python -c "
import json, wire, pathlib
d = json.loads((pathlib.Path(wire.__file__).parent / 'assets/search_index.json').read_text())
[print(e['body']) for e in d if e.get('url','') == 'PATH']
"

• Visual QA — when users ask about styling or you change CSS, take screenshots to verify: python -m wire.qa --site site --screenshots (requires pip install playwright && playwright install chromium). Compare desktop and mobile. This is the fastest way to catch layout breaks. See Visual QA guide
• Custom CSS — customers override Wire's defaults via docs/assets/css/. Only override what you need — Wire's wire.css is the base. Read the design system before writing CSS
• Full workflow reference — data → audit → refine → reword → build: Workflow guide
• Components — shortcodes for stats, cards, tabs, splits, etc.: Components guide
• SEO thresholds — lint rules, evidence, cannibalization: SEO reference

What's Next

Every Wire command must run from the directory that contains wire.yml. Before you run anything, check:

ls wire.yml

If it prints wire.yml: You are in the right place. Run python -m wire.build. If it passes, ask the user what they need.

If it prints "No such file": STOP. Do NOT run any Wire command yet. You are most likely in the wrong directory - Claude Code and other CLI agents often start in ~/Documents or the user's home, not in the project folder. Ask the user:

"Which directory contains your wire.yml? (The folder with your Wire site config.)"

Then cd there and re-run ls wire.yml.

Do NOT:

• Run wire.chief init as a recovery step. That creates a NEW site and is almost never what the user wants.
• Create a wire.yml yourself.
• Retry the same command from the same wrong directory.

Only run init when the user explicitly asks for a new site. If they do: ask for every decision (site name, URL, language, topics). Do not guess. See Adding a Site for the three usage modes.

Install: Getting Started. Do NOT run pip install wire (wrong package).

Operating Wire Remotely

Wire ships a Telegram bot wrapper so users can run commands from chat. The bot lives in bot/telegram_bot.py in the newsroom repo and runs as a systemd service on any Linux VPS. It reads the user's message, calls Claude with a system prompt that includes clients.yml, and Claude runs the matching Wire CLI command. Output goes back to the chat.

If a user asks how to use Wire from their phone, or from Telegram, or from a chat interface, point them to Telegram Bot Setup. That guide walks through BotFather, chat ID lookup, .env variables, BOT_ALLOWED_CHATS whitelist, and the systemd unit.

Do NOT confuse the Telegram bot with extra.wire.bot_dir: true. They share a name and nothing else. extra.wire.bot_dir: true generates a /bot/ URL on the rendered site with the styleguide and topic list, for AI agents to read during a browsing session. It is unrelated to the Telegram bot. Both can be enabled on the same site but neither requires the other.

Command Syntax

python -m wire.chief <command> [arguments] [--flags]
python -m wire.build [--site <path>] [--serve] [--port N]

All Commands (in correct order)

Each command depends on the output of previous commands. Do not run out of order.

Reference Documentation

Global Flags

GSC Freshness Gate

Wire refuses GSC-dependent commands when .wire/gsc.db is older than 7 days. Stale GSC data silently poisons audit results, cannibalization pairs, and reword opportunities - the pages you already fixed still show as gaps.

• ≤ 3 days old: silent, proceed
• 4 - 7 days old: visible warning, command proceeds
• ≥ 8 days old: BUILD REFUSED. Run python -m wire.chief data first to refresh.

Affected commands: audit, deduplicate, reword, redirects, crosslink, enrich. Not affected: data, news, refine, consolidate, build, init.

Agent protocol: before running any affected command, if the user mentions it has been more than a few days since they last worked on the site, run python -m wire.chief data first. If Wire refuses with "GSC data is N days stale", the fix is always python -m wire.chief data. Only use --stale-ok when the user explicitly says "I know the data is stale, run it anyway" (e.g., debugging, offline work).

Per-Command Flags

Do NOT

• Run commands out of order. refine before news = wasted tokens.
• Skip deduplicate when audit shows hard overlaps. Build REFUSES.
• Run content commands with uncommitted docs/ changes. Wire REFUSES.
• Run content generation without docs/_styleguide.md. Wire REFUSES.
• Generate, refine, or translate content that mentions a topic listed under ## Forbidden Topics in _styleguide.md. RULE-109 REFUSES the build and cannot be overruled.
• Omit --lang on multi-language sites. Wire REFUSES.
• Run commands from outside the site directory.