docs/ADAPTERS.md says what an adapter answers and what the forge checks #10056

I added docs/ADAPTERS.md, a one-page contract for adapter apps, written to the rules in docs/WRITING.md. It covers:

• the forge.json adapter block: source.name, source.hosts, and schedule.every as a whole number of seconds from 60 to 86400;
• the rule that every source host must also be listed in egress;
• POST /pull and its answer {pulled, skipped, cursor, errors}: each count is a whole number from 0 to 1,000,000, and the cursor is one line of at most 200 printable characters;
• what idempotent means: the same cursor gives the same result and writes nothing new, so records a repeated pull already holds count as skipped;
• what the forge does with a bad answer: the run is recorded as failed with a reason that names the problem, the previous cursor is kept, and the app is not woken to pull again before its next scheduled time.

What to check: the forge does not implement any of this yet. Nothing in src/ reads an adapter block, calls /pull, or records pull runs. The page opens with a Status section that says this, so no reader takes it for running code. The rest of the parent issue's work (the code that reads the block, scheduled pulls, pull runs) is not part of this change. Two choices in the page go beyond what the issue spells out:

• I read "the app is not woken to pull" as no early retry before the next scheduled time.
• Keeping the previous cursor after a bad answer is my addition.

Both should be confirmed or changed before the code is written.

Links: there is one line in docs/ARCHITECTURE.md under "Apps, runs, and the crew". There is also an entry in the docs/REFERENCE.md index, because test/readme-front-door.test.ts requires every top-level doc to be listed there.

To try it: read docs/ADAPTERS.md. The 12 test files scripts/fast.ts named for this change all pass (including the README and REFERENCE doc test), and so do bun scripts/gate.ts and bun x tsc --noEmit. No code changed.

🤖 Generated with Claude Code

Closes #10048

I added docs/ADAPTERS.md, a one-page contract for adapter apps, written to the rules in docs/WRITING.md. It covers:

• the forge.json adapter block: source.name, source.hosts, and schedule.every as a whole number of seconds from 60 to 86400;
• the rule that every source host must also be listed in egress;
• POST /pull and its answer {pulled, skipped, cursor, errors}: each count is a whole number from 0 to 1,000,000, and the cursor is one line of at most 200 printable characters;
• what idempotent means: the same cursor gives the same result and writes nothing new, so records a repeated pull already holds count as skipped;
• what the forge does with a bad answer: the run is recorded as failed with a reason that names the problem, the previous cursor is kept, and the app is not woken to pull again before its next scheduled time.

What to check: the forge does not implement any of this yet. Nothing in src/ reads an adapter block, calls /pull, or records pull runs. The page opens with a Status section that says this, so no reader takes it for running code. The rest of the parent issue's work (the code that reads the block, scheduled pulls, pull runs) is not part of this change. Two choices in the page go beyond what the issue spells out:

• I read "the app is not woken to pull" as no early retry before the next scheduled time.
• Keeping the previous cursor after a bad answer is my addition.

Both should be confirmed or changed before the code is written.

Links: there is one line in docs/ARCHITECTURE.md under "Apps, runs, and the crew". There is also an entry in the docs/REFERENCE.md index, because test/readme-front-door.test.ts requires every top-level doc to be listed there.

To try it: read docs/ADAPTERS.md. The 12 test files scripts/fast.ts named for this change all pass (including the README and REFERENCE doc test), and so do bun scripts/gate.ts and bun x tsc --noEmit. No code changed.

🤖 Generated with Claude Code