ArcBlog

English ｜ 中文

ArcBlog is blog software you deploy yourself: the content belongs to its author and the reader relationship is not held by a platform. Individually deployed instances discover and redistribute each other through verifiable roles, instead of everyone crowding onto one platform. Technically: content-node software using DID as identity and AFS as the resource layer.

The single source for that positioning = product §1.1 (goal ≠ current state; how to read the two apart: guide §5).

Language note: the long-form documentation under docs/ is Chinese-first. This README and CLAUDE.md are the English entry points; every link below states its own status, and the 30-minute onboarding: docs/00-getting-started.md (English) ｜ docs/00-新手上路.md (Chinese).

---

1. What this is (30 seconds)

Question	One line	Where to read
What is it	A Blocklet (blocklet.yaml) built on the Arc/AUP stack — not a Node app: no bundler, no dev server, and the AUP application itself has zero runtime dependencies	Architecture
Unit	One ArcBlog instance (one deployment of this code)	Positioning §2.1
Roles	Aggregation is the agent's job: deploy a node and stake its studio NFT to the same factory address to be discovered — the staked-asset list of that address is the node registry. Human-side roles = C/R/O/A/G (creator / reader / node operator / agent integrator / platform governor)	Users & roles §1 ｜ Positioning
What works today	Node-NFT on-chain lifecycle implemented (beta, a tx per step); discovery/enumeration implemented (listStakes on both adapters; the read-only real-chain probe passed, so ?page=registry answers)	Ledger ｜ Probes
Who uses it	Creators / readers / node operators / agent integrators / platform governors	Users & roles

Do not mistake the goal for the state: 01 §6 ("irreplaceability") and §6.5 ("a mechanism, not a closed loop") must be read together (guide §5).

---

2. Run it (5 minutes)

Prerequisites: Node (measured here on v24.14.0, ESM), the arc CLI (measured 2.0.0-beta.50), and a local ARC daemon. npm install is needed only for --adapter ocap (five chain-script dependencies). The authority for that environment = Technology §1.2.

# (1) the DSL gate — issues must be []
arc dsl validate --json

# (2) the fast tier (~2 s, never writes an instance) — take the case count from the runner itself
npm test

# (3) publish a post (the CLI is the only path that writes real authorship and normalized tags)
node scripts/arcblog-lifecycle.mjs publish \
  --title "My First Post" --author-did did:key:z... \
  --body-file post.md --category technology --tags "a,b"

# (4) query what is published
node scripts/arcblog-query-posts.mjs published --category technology

I want to…	Command	Authority
Run the gates (validate / fast tier / build)	arc dsl validate --json → npm test → npm run build	Quality gates §7 ｜ gate discipline
Make a .aup change take effect	arc service restart -i default and arc blocklet run . -i default (a deploy alone is not enough)	Build/deploy §2
Build safely (the only entry)	npm run build	Build/deploy §1
Deploy to the local Pages instance	node scripts/arcblog-deploy.mjs --dry-run	Build/deploy §4
Diagnose a problem	arc service list, then match the symptom	Operations handbook ｜ Task navigator
Look up an error code	—	Error-code index

The full command manual = Build/deploy §6; this file does not restate it.

---

3. Where to read

New here? Start with docs/00-getting-started.md (30 minutes: what it is → how to run it → where the code and data live → and, most usefully, what not to read). The Chinese twin is docs/00-新手上路.md. The map below is for when you already know what you are looking for.

Who you are / what you want	Start here
First contact	§1 of this file → Product guide → Positioning §0 (five questions)
I will write docs/**	Documentation charter (stage gates / writing rules / term ownership)
I need to find a document	Index and reading paths
I will change code or release	CLAUDE.md (implementation facts, every command) → Development docs → Ledger
How far is requirement X?	Requirement ledger (the only status authority)
I have to follow the team rules	Team & development rules
Is a past decision still valid?	Decision record

The eight volumes (structure in the charter §1; the only ledger of stage status and frozen records = charter §2.1):

docs/01-产品概念/  02-产品需求/  03-产品设计/  04-UI设计规范/
docs/05-开发文档/  06-功能开发列表/  07-团队与开发规范/  08-其他/
docs/team/         the workbench (stage logs + review/verification records — not product docs)

---

4. Where to change what

You want to change	Change	Then run
A page / copy / interaction	.aup/** (every console section is a real page)	arc dsl validate --json + npm test
Record fields / required keys	world/*.yaml (12 schemas; authoritative list = Data model §1)	the same + npm run build
Read/write permissions	replicated in blocklet.yaml (the only authoritative gate; networkRead is merely a prefix allowance)	the same + npm run build
Public SSR surface / theme	pages/**, .web/** (a Web Device has no AFS channel)	the same
CLI / operations scripts	scripts/** (a new test counts as live unless it is listed in FAST_TESTS)	npm test, plus the targeted run below
Chain adapter	scripts/lib/chain.mjs (mock / ocap)	a targeted run + human approval (funds/chain)
Documentation	docs/0X-*/**	follow the charter

Two rules you cannot skip (details in the team rules):

1. Write scope: only the files inside your role's glob; ask the Lead before crossing it.
2. Commits: the Lead is the only committer; teammates must not git commit / push / reset. Checkpoint commits, exact paths (never git add -A), and a git diff read before committing (commit discipline §3).

If your change touches a CLI, an AFS record, the chain adapter or a daemon route: do not run the whole live tier (~21 minutes and it writes a shared instance). Run the affected file only, holding the lock:

npm run test:file -- scripts/arcblog-media.test.mjs   # write docs/team/.gate-lock first, remove it after

External reference: ArcBlock's technical docs https://www.arcblock.io/en/docs/ — check them before guessing any ARC / AFS / AUP / Blocklet API (the authority for capabilities and degradations is Platform boundaries).

---

5. Repository layout at a glance

blocklet.yaml   identity / publishable metadata / sites.bindings / scope / permission tables
.aup/           the application: app.aup (14-line manifest) + man/ + pages/**/*.aup + wrapper + locales
world/*.yaml    AFS record schemas (12)
pages/          SSR page definitions (/p/en/…, rendered by .route/web)
.web/           public Web Device components and themes (hero-carousel, theme-bridge)
.route/         daemon route mounts: / → AUP, /p → SSR
agents/         Agent Access declarations (the runtime serves /mcp and /p/llms.txt)
scripts/        operator Node CLIs + node:test suites (the fast tier's whitelist is FAST_TESTS)
seed/           default settings records (tone / palette / theme)
dist/           build output (refreshed by npm run build; **a bare arc blocklet build copies keys into dist/**)

The full per-directory, per-layer and per-write-channel description = Architecture and CLAUDE.md (the single entry for implementation facts).

---

6. What this file deliberately does not repeat

• Stage gates, documentation rules, term ownership → Documentation charter.
• What the platform can and cannot do → Platform boundaries (+ prohibitions and degradations); unverified → Probes §1.
• How the gates operate (tiers / lists / criteria / real-vs-fake red) → Test tiers and quality gates.

Actions that require a human decision (irreversible or outward-facing): push, real funds and chain writes, deleting instance data, the final rewrite of the entry files, and product-scope rulings — the list lives in Human checkpoints §6 and, in working form, docs/team/human-checkpoints.md.

7. Licence and contributing

• Licence: Apache License 2.0, with NOTICE and third-party attribution in THIRD_PARTY_LICENSES.md. The upstream platform (ARC daemon, AFS, AUP, the chain SDKs) is ArcBlock's and keeps its own terms.
• Contributing: read CONTRIBUTING.md first — the four gates, one authoritative file per fact, and "a guard must be proven able to fail". There is no CLA: submitting implies the same licence (Apache-2.0 §5).
• Roadmap: not maintained anywhere else. Requirements and status = docs/06-功能开发列表/ (56 rows; zero unstarted, zero in progress); to-dos = docs/team/human-checkpoints.md; platform boundaries = docs/05-开发文档/02.
• Security: SECURITY.md (report privately, not as a public issue). Conduct: CODE_OF_CONDUCT.md.
• Changes: CHANGELOG.md (the version lives in blocklet.yaml, releases are git tags).