The docs in your repo deserve better.

Comment on docs instead of diffs, get briefed on any doc before you read it, and see where code and docs disagree. All of it stored in your git repo.

You're on the list.

acme/platform / docs/specs/billing-migration.md

Fact Check

This doc is out of date on what the worker checks before it writes. The worker checks billing.schedule now.

Briefing

Written by AI, Oct 7

This is the plan for moving the 1,400 accounts still on grandfathered annual pricing onto the new billing schedule. A worker backfills them in batches of 200 during the Friday window, and support runs the smoke checks once the last batch lands. Accounts opened before the Stripe upgrade keep their old anniversary dates.

priya · Updated 3 days ago · In review

Billing migration

The worker reads billing.plan_version and refuses to write when the flag is unset, so a partial run leaves nothing to undo.

Accounts

Every subscription created after March is already on the new schedule, so the migration only touches the 1,400 accounts still on grandfathered annual pricing. Anything opened before the Stripe upgrade keeps its old anniversary date.

Cutover

The backfill runs in batches of 200 and holds the write lock for under 400ms. The Friday window is the only one with support fully staffed.

Support runs the smoke checks from the runbook once the last batch lands. Anything still on the old schedule after that counts as a bug.

3 open · 1 resolved

Fact Check Out of date since Sep 2

billing.plan_version

The worker checks billing.schedule now.

Commit a3f21c9 removed billing.plan_version in the Stripe upgrade, and the worker moved to the schedule the same day.

Evidence 2 sources

billing/backfill.ts

if (!billing.schedule) return skip(sub) 42

Commits

Stripe upgrade: drop legacy plan fields a3f21c9

There's a good case for keeping docs in the repo.

Versioned and reviewed like code, context for your agents.

But GitHub treats docs as code.

The diff is hard to read, and the rendered markdown doesn't take comments.

docs/specs/billing-migration.md +14 -1

@@ -18,8 +18,21 @@ ## Billing migration

18 18 ## Rollout

19 19

20 20 Annual plans move off the legacy proration table in three waves.

21 21 Each wave is gated on the one before it settling.

22 22

23 See the [rollout doc](../ops/rollout.md) for the order of operations.

23 | Wave | Accounts | Gate |

24 | ---- | ------------------- | --------- |

25 | 1 | 120 internal | manual |

26 | 2 | 1,400 grandfathered | 48h clean |

27 | 3 | remainder | 48h clean |

29 ```mermaid

30 flowchart LR

31 W1[wave 1] --> C{clean 48h?}

32 C -->|yes| W2[wave 2]

33 C -->|no| H[hold]

34 ```

36 Order of operations is in the [rollout doc](../ops/rollout.md).

24 37

25 38 ## Rollback

Rollout

Annual plans move off the legacy proration table in three waves. Each wave is gated on the one before it settling.

See the rollout doc for the order of operations.

Wave	Accounts	Gate
1	120 internal	manual
2	1,400 grandfathered	48h clean
3	remainder	48h clean

Order of operations is in the rollout doc.

Rollback

In Spectagon, docs read like docs.

Beautiful to read, and commenting works the way you'd expect from a docs tool.

acme/platform / docs/architecture/webhook-delivery.md

Webhook delivery

Every event we emit is delivered at least once. Workers claim pending rows from webhook_outbox and try each delivery up to four times.

select id from webhook_outbox
where status = 'pending'
order by created_at limit 200
for update skip locked

Attempt	Delay	Elapsed
1	none	0s
2	30s	30s
3	5m	5m 30s
4	1h	1h 5m 30s

Comments show up on your pull request.

Your teammates see them and can reply from GitHub, without ever opening Spectagon.

docs/specs/billing-migration.md #482

8 The worker reads `billing.plan_version` and refuses to write when the flag is unset, so a partial run leaves nothing to undo.

spectagon bot commented 2 days ago

priya via Spectagon:

a partial run leaves nothing to undo

Invoices it already emailed can't be unsent. Can we hold sends until the last batch lands?

sam replied yesterday

Holding them means a second job to release them afterwards. Could we void and reissue instead?

Your comments are commits in your own repo.

Cancel your account and they're still there, readable with plain git.

$ git log --oneline refs/spectagon/reviews

3e0f5d2 agents: docs/rfcs/0042-webhook-retries.md

7c41ab9 review: 1 comment on docs/rfcs/0042-webhook-retries.md

b19c884 settle 2 threads

$ git show 7c41ab9:threads/5d0e2c1a-7f3b-4e8a-9c61-b2a4d8e0f317/root.md

file: docs/rfcs/0042-webhook-retries.md

anchor:

text_snippet: six attempts over 24 hours

author: dana

created_at: 2026-09-19T14:02:11Z

Shipped as eight in the end. Worth fixing

here before someone copies it.

Get briefed before you read.

A paragraph on what the doc says, what's changed, and what to watch for.

Briefing Updated by AI, Jun 26

This doc sets how many requests customers can make to the public API. Each API key gets 100 requests a minute, and enterprise customers can ask for more. A customer over the limit gets an error that says when to try again.

Watch for

Nothing caps a customer across keys. One customer could create ten keys and get ten times the limit.

Your docs get checked against your code.

When a sentence stops being true, it gets flagged, with the code that shows what changed.

acme/platform / docs/architecture/auth.md

Fact Check

This doc is out of date on these points.

What login returns Login returns a random session token, and the gateway looks it up on every request.
How long a session lasts A session lasts seven days, and revoking it ends it straight away.
How failed logins are counted Failed logins are counted per IP address, so everyone behind one office address shares the limit.

Authentication

The auth service issues a signed JWT on login, and every service behind the gateway verifies it locally against the shared public key. A token is good for fifteen minutes and nothing revokes it early, so a suspended account keeps reaching the API until it expires.

Failed logins are rate limited to five per account per minute, and the gateway pages on call once one account crosses a hundred in an hour.

Fact Check Out of date since Jun 11

a signed JWT

Commit 4c1e07b replaced JWT signing with session tokens on Jun 11. Nothing on main defines signJwt now.

Evidence 3 sources

auth/session.ts

token = randomBytes(32) 111

gateway/verify.ts

sessions.get(token) 18

Commits

auth: drop JWT signing 4c1e07b

Fact Check Out of date since Jun 24

fifteen minutes · nothing revokes it early

A session lasts seven days, and revoking it ends it straight away.

Commit d0b8e41 set SESSION_TTL to seven days on Jun 24. Revoking a session deletes it.

Evidence 3 sources

auth/config.ts

SESSION_TTL = 7 * DAY 9

auth/session.ts

sessions.delete(token) 131

Commits

auth: sessions last 7 days d0b8e41

Fact Check Out of date since Aug 3

per account

Failed logins are counted per IP address, so everyone behind one office address shares the limit.

limitKey switched from the account to the client IP in commit 2b90d1c on Aug 3.

Evidence 2 sources

gateway/rate-limit.ts

key = clientIp(req) 34

Commits

gateway: rate limit by client IP 2b90d1c

Start with one repo.

It installs as a GitHub App and no action is required from your teammates.

You're on the list.

FAQ

Where do my comments live?

In your repo, on refs/spectagon/reviews: one directory per thread, markdown with frontmatter. Fetch the ref and read it with git log and git show.

Do my teammates need Spectagon accounts?

No. Your comments post to the pull request, and anything they write back there lands in the same thread.

Can I comment on a doc after the pull request is closed?

Yes. Open any doc on main and comment on it.

What access does the GitHub App need?

Read and write on repository contents and pull requests, write on commit statuses, and read on metadata. Spectagon writes review threads to refs/spectagon/reviews, opens one setup pull request only when someone asks, and never pushes to a branch you made.

Is it GitHub only?

Yes, today. Threads are stored as ordinary git objects, so the format itself does not depend on GitHub.

Can I write docs in Spectagon?

No. Spectagon is for reading and commenting on docs that are already in your repo. Keep writing them in your editor or with your agent, and commit them as usual.

What does it cost?

It's free during early access. Pricing hasn't been decided yet.

Does it work with my coding agent?

Yes, with Claude Code and Codex. One pull request adds a check script and hooks, so your agent sees the same flags and open comments you do.