Onboarding: replace the one-size Conway first-doc with a per-user bio page (fixes global-slug collision)

[yayashuxue]

Summary

The first-doc onboarding tells every new user to build the same doc — "Conway's Game of Life" (FIRST-DOC.md Step 2). Because the hosted slug namespace on tdoc.dev is global, the second person to run onboarding collides on the default slug and the publish is rejected with not_doc_owner (403) / slug_taken (409). This is not a corner case — it happens to the N-1th of every N onboarding users.

We should rethink onboarding so that (a) it doesn't collide by construction, and (b) the first doc is something the user actually wants to keep.

The bug (reproduced with Mike)

Mike ran onboarding today. Sign-in succeeded (xmike565-ai), but the upload was rejected:

• conways-game-of-life was already claimed by another account.
• not_doc_owner (403) = the slug already has meta owned by a different hosted account; the tdoc.dev slug namespace is global, so ownership can't be overwritten.
• The workaround was to re-publish under a distinct slug — but a brand-new user hitting a 403 on their very first publish is a broken first run.

Source: FIRST-DOC.md Step 2 hardcodes the Conway's Game of Life doc for everyone; worker/worker.js returns not_doc_owner on cross-account slug writes. Global namespace + shared default slug = guaranteed collision.

The product take

Everyone making their own Conway's Game of Life doesn't really make sense — it's a nice demo of the mechanics (live artifact + commentable board), but it's throwaway and identical across users, which is exactly what causes the slug collision.

We don't necessarily need Conway. What we probably do want is a community version: the first doc is a personal bio / blog page — LinkedIn + GitHub + whatever makes sense for them — that they'd actually keep and share.

Proposed:

• First doc = a personal bio page, not Conway's Game of Life.
• Slug is namespaced to the user's GitHub handle: tdoc.dev/d/<github-account>-bio. This sidesteps the global-namespace collision by construction (each account gets a unique default slug) and doubles as a durable landing page / mini-blog for that person.
• Keep the onboarding lesson (leave a comment → ask your agent to fix it → new version → replies → share the link) — just attach it to a doc worth keeping instead of a throwaway.

Evidence this format has legs

Real users are already producing substantial docs on tdoc. Fiona wrote a ~150-page long-form piece — her "绩点效应 / singularity-effect" paper:

https://tdoc.dev/d/singularity-effect/v/1#h-%E6%91%98%E8%A6%81

Open questions

• Bio content: seed from GitHub profile automatically vs. ask the user a couple of prompts?
• Do we retire the Conway doc entirely, or keep it as an optional "show me the interactive-artifact trick" second step?
• Slug collision fallback if <github-account>-bio is somehow taken (e.g. re-publish, versioning).

cc @serenatan

[serenakeyitan]

Both halves shipped. Leaving this open for you to close, since it's your issue.

The collision — the half that actually breaks people — is fixed in #269. You were right that replacing the doc does not fix it on its own: SKILL.md:318 picks a slug "from the prompt, kebab-case, ≤4 words", so the new subject resolved to what-ai-knows for everyone, and the development copy had already claimed it globally. New subject, same 403. The slug now comes from the person (what-ai-knows-<name>), falls back to the GitHub login, and a 409/403 is retried with a suffix rather than surfaced — the user is watching their first doc appear, and a namespace collision is not a message for them to read.

The doc is rewritten in #265. It is no longer one-size: it is What does AI know about you?, assembled from the traces every AI assistant on the machine has left, with the reader's name in the title. Each section opens with a trait and proves it with a chart. It is the one document no other tool can write, because every other product sees only its own history.

Three related fixes came out of building it:

• fix: the first doc publishes privately instead of ending at localhost #266 — it publishes to tdoc.dev with --visibility private rather than ending on a localhost URL. My first draft said "build it, open it locally, and ask", which reintroduced exactly what /tdoc new publishes to tdoc.dev and never hands back localhost #239 had just fixed. The privacy concern behind that wording is an access problem, not a hosting one.
• fix: resolve the skill directory at runtime so the self-update can run #268 — the automatic self-update had never run on any machine. It was gated on a placeholder token that an install script was supposed to substitute; that script does not exist in the repo, so the guard was false everywhere and failed silently.
• ONBOARDING.md Step 5 scaffolded a three-line Hello, tdoc. placeholder and never mentioned FIRST-DOC.md — the whole recipe was unreachable from the flow meant to run it.

Worth flagging for the note in your issue about slugs: this makes #190 more load-bearing, not less. Every user now wants a slug carrying their own name, which is exactly the contested space that issue is about.

[yayashuxue]

@serenakeyitan onboarding issue is written up and ready for you — assigning to you. TL;DR: the fixed "everyone builds Conway's Game of Life" first-doc collides on tdoc.dev's global slug namespace (Mike hit not_doc_owner 403 on his first publish today). Proposal in the issue: make the first doc a per-user bio page at tdoc.dev/d/<github-account>-bio, which is collision-free by construction and worth keeping. Open questions at the bottom — take a look when you get a sec 🙏