# A2IO

> A2IO is a cross-platform content archiving and knowledge-routing CLI for humans and agents.

Official website: https://a2io.zslren.com/
Machine-readable manifest: https://a2io.zslren.com/agent.json
Agent guide: https://a2io.zslren.com/docs/agent.md
Stable update manifest: https://a2io.zslren.com/update/stable.json
Health endpoint: https://a2io.zslren.com/healthz

## What A2IO does

A2IO reads content from X bookmarks and links, WeRead shelves / public-account articles / favourites, GitHub Stars or one repository, MediaCrawler JSONL or SQLite exports, RSS, URLs, Zhihu, Douban, Weibo, Bilibili, Toutiao, Hacker News, V2EX, YouTube and Telegram. It can archive or route content to Obsidian and IMA.

The core model is: source -> normalized records -> idempotent sync route -> destination. Routes preserve source IDs, content fingerprints, cursors, delivery status and retry state. A route should be configured once and then invoked by an external scheduler.

## Installation and handshake

1. Download the stable artifact for the current OS and architecture from `/update/stable.json`. The manifest is signed with Ed25519 and each artifact has a SHA-256 digest.
2. Put credentials in an OS secret store, environment variables or a local `.env` file. Never put cookies, API keys, license keys or private keys in an agent prompt, route record, log or Markdown file.
3. Run `a2io capabilities --json`. Require `product=a2io`, a valid `edition`, `version`, `contract_version`, platform, architecture and the required capability before doing network or write operations.
4. For a local Obsidian vault, run `a2io init --vault <absolute-path> --json` and then `a2io doctor --json`.

## Safe command examples

```text
a2io capabilities --json
a2io version --json
a2io sources list --json
a2io doctor --json
a2io update check --channel stable --json
a2io update apply --channel stable --json
a2io sync --source rss --param feed=<RSS_URL> --json
a2io sync --source url --param url=<URL> --destinations obsidian --json
```

Use `--json` for automation. Parse the returned status, counts, IDs, warnings and errors; do not infer success from human-readable output.

## Pro workflow

The Pro binary uses the same command entry point and must still be gated by the live capability handshake. Before WeRead App / MP, IMA protocol, persistent routes or monitoring, check:

```text
a2io capabilities --json
a2io runtime status --json
a2io license status --json
```

Pro onboarding is register -> device -> license redeem -> platform QR login. Use the installed Pro onboarding guide for the exact account flow. Common persistent routes include:

```text
a2io mp route add --url <公众号文章链接> --ima-knowledge-base <ID> --ima-folder <目录ID> --ima-mode url|html|markdown --initial baseline --json
a2io x route add --account-id <X账号> --ima-knowledge-base <ID> --ima-folder <目录ID> --ima-mode url|html|markdown --initial baseline --json
a2io github route add --url https://github.com/<owner>/<repo> --content-mode readme --ima-knowledge-base <ID> --json
a2io monitor auto-sync --once --force --json
```

IMA supports `url`, `html` and `markdown` destination modes. Obsidian supports the same three modes. `baseline` records existing items without importing them; use `full` only when historical backfill is explicitly requested.

## Scheduling

A2IO CLI commands are one-shot and do not start a permanent daemon. Use Windows Task Scheduler, Linux systemd timer / cron, or macOS launchd to call `a2io monitor auto-sync --once --json`. The current Pro route monitor is internally throttled to 10 minutes in this workspace; `--force` explicitly bypasses the current throttle for a manual check.

## Agent operating rules

- Read `/agent.json` and `/docs/agent.md` before choosing a command.
- Handshake first; use only capabilities returned by the installed binary.
- Inspect configuration with read-only commands before a sync.
- Require an explicit destination and absolute local paths; never guess a Vault or knowledge-base folder.
- Prefer `baseline` for a new persistent route and test it before enabling automation.
- Preserve user edits and treat `unchanged`, `skipped`, `conflict` and `failed` as distinct outcomes.
- Do not print or persist secrets. Do not bypass platform access controls or anti-bot checks.
- Report `run_id`, source counts, delivery counts and warnings from JSON output.

## Documentation map

- `/docs/agent.md`: complete machine-oriented quick start, routes, security and troubleshooting.
- `/docs/quickstart.md`: shortest Free / Pro setup.
- `/docs/configuration.md`: credentials, destination modes and route principles.
- `/docs/update.md`: signed cross-platform update protocol.