Browsable URLs: people at the root, one address per plan, live libraries

[HamptonMakes]

Plans had ugly addresses and no home. /plans/019d54a7-ea13-72d5-bc54-fc44cb9b939a
tells you nothing, can't be read aloud, and can't be guessed. Worse, a plan could
live on any number of shelves at once, so "which library is this in?" had an answer
that depended on who was asking — which makes a canonical URL impossible. A document
with three locations has three addresses and no home.

This gives every plan one place and one address.

Browsable URLs

/sam                                    Sam, and Sam's library
/sam/liveorder                          a folder
/sam/liveorder/cart-state-machine       a document

People are the root namespace. Every prefix is a real page, so trimming a segment off
any URL walks you up the tree. One action serves all three, because they're one thing
— a place in a library — and which of the three a path names isn't knowable until the
segments are resolved.

Resolution walks one segment at a time: handle, then folder slug within the previous
folder, then a plan slug in whatever folder we landed in. Nothing stores a joined
path, which is why renaming a folder can't invalidate anything beneath it.

Segments strip whatever the URL already says — the handle, every ancestor folder, the
plan type, the word "plan" — so you get /sam/liveorder/cart-state-machine instead
of /sam/liveorder/liveorder-cart-state-machine-plan. Two plans whose titles
slugify the same way get a 4-char ~suffix on the leaf, collision-only, from an
alphabet with no 0/o/1/l.

Unicode survives: /aiko/operations/reliability/信頼性向上ロードマップ-2027年前半.
Slugs normalize NFC and keep Unicode letters. Library handles stay ASCII, since a
handle is the root of every URL under it and gets typed and read aloud.

Everything that isn't a place lives under _

Handles sitting at the root means the app's own pages have to move out of the way:

/_/settings          /_/search          /_/notifications
/_/plans             everything you can see, wherever it lives
/_/libraries         every library you can browse

That single character is the whole reservation. A handle can never be _, because
slug rules strip non-alphanumerics, so the split is structural rather than a list
someone has to remember to update. _ is reserved inside a library too (/sam/_/…,
by the same mechanism), so library-scoped pages have somewhere to go later that can't
collide with a folder name.

Rails' scope "_" prefixes paths and not helper names, so settings_path and
publish_plan_path read the same at every call site as they did before.

The legacy block near the bottom of the router is the one fixed list, frozen at the
paths that shipped before this — /plans, /people/:id, /settings, /search and
the rest all 301 onward. It can shrink; it never has to grow. /api and
/agent-instructions stay at the root: they're published external contracts, in every
API response and in llms.txt.

A person's page is their library

/people/:id rendered a read-only shelf. /l/<handle> rendered a different read-only
shelf. Neither had filters, folder counts, or "since you last looked" — which is what
made someone else's library feel like a lesser app rather than the same app, pointed
somewhere else.

Both are gone. Every library renders one page. What you can do to what's in it is a
question for the buttons — Library#writable_by?, surfaced to the views as
@can_write — not a question of which view to render. So browsing a colleague's
library gives you their folder tree, their filters, their counts, and what's changed
since you last looked, minus New folder and drag-to-file.

The identity that used to live on the profile page is now the header of that one page:
avatar, name, title · team, handle, and the directory link if the host provides one.
/people/:id 301s onto it.

Two consequences worth naming:

• Library rows are created with the user now, not on first touch. A library was a
  filing cabinet, so materializing it lazily was fine; it's a person's page now, and a
  link to a colleague who has never signed in has to work. The migration backfills the
  rows for everyone who predates this.
• Folder clicks stay inside the library you're browsing. Folder navigation was
  built out of ?folder=<id> against your own workspace, so clicking a folder in
  someone else's library bounced you into yours.

Live libraries

Filing a document, moving it, retitling it, hiding it, creating or renaming a folder —
all of it changes what a library page shows, and none of it used to reach the page.
Now every one of those tells the library, and every browser watching that library
re-fetches. Readers too, not just the owner: a filter you're looking at is as stale as
one you could edit.

broadcast_refresh_to rather than streamed fragments, because no fragment can be
shared — visibility is per-viewer, the folder and filters are per-viewer, and the forms
carry per-session tokens. The broadcast carries no content, just the news that there is
some, and each browser re-renders its own page. With
turbo-refresh-method: morph + turbo-refresh-scroll: preserve, a page you're reading
doesn't blink, lose your scroll position, or close the popover you just opened because
someone else filed something. Turbo tags the stream with the acting request id, so the
browser that caused the change doesn't refresh twice.

Per library rather than per folder: a rename high in the tree changes every listing
beneath it, so a folder-grained stream would have to fan out to all of them.

One place per plan

has_many :placements → has_one :placement, with a unique index and a migration
that collapses existing rows (keeping the author's own; oldest otherwise). Filing a
plan somewhere else is a move, never a second copy. The Save button that filed
someone else's document onto your own shelf is gone.

Plan#library is wherever it's filed, falling back to its author's library when it
isn't filed at all. Every reader sees the same location, because there is only one.

Moving takes authority on both sides: write access to the destination, plus
authorship or write access to the library it sits in now. That second half is the
seam that will let a team reorganize its own library without letting anyone walk off
with someone else's document. from_library_id on the Organize move ops becomes a
no-op — filing somewhere new already takes it out of where it was.

Renames don't break links

Old URLs keep working through coplan_url_aliases. Two kinds:

• exact — one URL to one URL, for a retitled plan.
• prefix — rewrites the head of a path, so one row covers everything beneath a
  renamed folder or handle. O(renames), not O(documents).

That table is a cache, not the record. Every rename is already in plan_events
and library_events with before/after values, append-only, so the rows can be
rebuilt from scratch — which is what will make pruning safe later. Aliases are
consulted only after the real walk fails, so a live page always beats a stale
alias, and chained renames follow up to 5 hops (which also breaks any cycle bad data
could introduce).

/plans/<uuid> is no longer canonical

It 301s onto the readable address — permanent, because the id form is the page's old
name, not a redirect-of-the-day — carrying the query string so ?thread= deep links
and the legacy ?tab=history hop still land. HTML GETs only: a Turbo Frame fetch or
a JSON caller asked for that exact URL and gets a response, not a hop.

Every link the app generates now points at the readable form directly — views,
controller redirects, search results, web-push payloads — so nobody pays for the
extra hop. The document page carries rel=canonical for anything arriving the old
way. Path building lives in Urls::Canonical so jobs and push payloads can reach it
without a view context.

Cross-document links read as documents again

Reference only knew /plans/<uuid>, so a link copied out of the address bar — which
is now every link — landed in the References footnote as a generic "link" with no
target_plan. It understands the readable form too, resolving through the same segment
walk the router uses, aliases included: a link written before a rename still names the
document it was always about.

The catch is that /plans/<uuid> was self-identifying and a readable path isn't.
/sam/liveorder/cart-roadmap is shaped like any other site's URL, so matching on shape
alone would have typed half the links people paste as CoPlan documents. Classification
now takes the request host and only treats a readable path as ours when it is ours;
resolution (which plan) stays separate from classification (what kind of link),
because the extractor runs in a job with no request to ask.

Also in here

• A folder could take a document's address. Collision checking asked only
  whether another plan held the slug, but resolution hands the segment to a
  folder when both want it — so a plan sharing a sibling folder's slug had no
  reachable address, and /plans/<uuid> 301'd onto the folder. Folders now count
  as siblings in both directions: a plan created beside a same-named folder takes
  the ~suffix, and a folder created or renamed onto a plan's segment re-slugs
  the plan it would have shadowed. Folders never take a suffix — a folder's
  segment appears in every URL beneath it — so the plan is the one that moves.
• A prefix alias skipped the path it was recorded for. Candidates were every
  ancestor of the requested path and not the path itself, so a folder rename
  fixed every link into the folder except the link to the folder, and a renamed
  library handle never matched at all (a one-segment path has no ancestors).
• Library counts left out loose plans. A plan at a library root has no
  placement row by design, so counting placements called a library of nothing but
  unfiled work "empty" while browsing it showed the plans.
• /_/libraries could omit your own library. It read the table directly — exactly
  the path that skips the materialize-on-first-touch invariant. Moot now that rows are
  created eagerly, but the accessor is still what the index goes through.
• The truncation lists never included libraries. Two specs run without
  transactional fixtures and clean up by hand; their lists predate libraries and
  folders, so those rows accumulated across runs. A handle is globally unique, so a
  leaked row kept alice reserved. That leak is what had been hiding the bug above.

Known gaps

• Inline links in document bodies are not rewritten. Nothing edits your markdown
  on someone else's rename. The link keeps working (the alias catches it and the
  address bar converges), but the text stays stale until someone edits it. Deliberate
  — rewriting people's prose seems worse than a redirect.
• Alias pruning and rebuild aren't built yet. The table has the index for
  eviction and the rebuild is possible from events, but neither job exists. Nothing
  prunes today, so nothing breaks; the safety argument is currently theoretical.
• Cross-library moves log only the destination. Unreachable today (one library
  per owner) and flagged in Plans::Place as the team-library seam.
• A segment can change hands. When a folder takes a plan's segment, the plan
  gets a new address and anyone following the old link lands on the folder that
  now owns that name — a live page beats an alias, deliberately. The document
  keeps an address instead of losing one, which is the trade I'd make again, but
  it isn't a redirect to the same thing.
• Readable-link recognition assumes the engine is mounted at /. Mounted at a
  subpath it stops recognizing its own readable links rather than mis-recognizing
  other people's — it degrades toward "generic link", never toward a false positive.

Testing

1715 examples, 0 failures, rubocop clean. All three migrations roll down and back up clean.
Dev seeds showcase the feature: a prefix alias (sam/order-platform →
sam/liveorder), a ~gaxa collision suffix, a chained rename, Unicode titles in
Japanese, Arabic, and Spanish, and a seeded cross-document link written the way an
agent would write it now — by readable address, resolved to a real reference.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 092f582755

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".