Product rethink: visibility over status, personal libraries, profiles, three surfaces

[HamptonMakes]

Implements the product rethink from the CoPlan Rethink PRD end to end, in four phases (one commit each, plus a migration commit and polish).

Note

This supersedes #146, which is now obsolete — the org-global folder design it built on was replaced by personal libraries in the PRD.

1. Status is dead

• The 5-state status lifecycle is replaced by visibility (draft/published) + archived_at. Migration maps brainstorm→draft, abandoned→published+archived, everything else→published (with developing/live preserved as tags).
• Plans are born published. Draft is API opt-in ("visibility": "draft" on create), not the starting state.
• Drafts are unlisted, not locked. Anyone with the URL can read a draft (PlanPolicy#show? is open); discovery — lists, feeds, search, counts, shelves — goes through one predicate (PlanPolicy#listed? / Plan.visible_to), never inline checks.
• Publishing is explicit, confirmed, and one-way; archive is the off-ramp. Legacy API status still accepted (mapped) and emitted (legacy_status) for the deprecation window; unknown legacy values now 422 with guidance.

2. Folders became personal libraries

• CoPlan::Library with a polymorphic owner (users only in v1); every user always has one, materialized on first touch (Library.for, race-safe). Folders belong to their library; write access is the library's call (writable_by?).
• Plan↔folder is now a first-class join, CoPlan::PlanPlacement (who placed it, when; unique per plan per library) — the same plan can sit on many people's shelves. Shelving someone else's published plan is a normal action.
• Plans::Place is the single write path for shelving (web drag-and-drop, row menu, and API all use it).
• Everything folder-flavored is viewer-relative: the API's folder_id/folder_path mean "where you shelved it", workspace rows show your shelf, and the sidebar tree is your library.
• Libraries are browsable read-only (/libraries/:id), and plan pages grew a "Shelved in" folder-jump strip.

3. Profiles + directory adapter

• /people/:username-or-id — identity, published plans, and the library shelves embedded. Only publicly listed work appears, even on your own profile.
• New host hook config.directory_profile (People API adapter point): enriches name/avatar/title/team and adds a directory link-out; failures degrade to the local profile. Author names across the app link to profiles.

4. Three surfaces

• Home (/home, the new signed-in root): activity feed over published work, rolled up per plan per day (CoPlan::HomeFeed), plus search that now finds people as well as plans.
• Workspace (/plans): your operating center — your plans (drafts included) + your placements, needs-attention strip, folder tree.
• Nav: Home / Workspace — after design review, the library is no longer a third destination (see design round below).

One deliberate deviation from the PRD: the workspace main pane still groups by plans/drafts rather than by folder — the folder tree + drag-to-file in the sidebar covers folder organization, and the visibility groups are what make drafts-you-never-published visible. Easy to revisit.

Design round (post-review feedback)

• IA simplified: the Library page stopped being a separate nav concept — the workspace sidebar folder tree is "My library" (with a "Public view →" link to the read-only page others browse from profiles). Org-wide "All plans" browsing left the workspace sidebar; discovery lives on Home, search, and profiles.
• Published is the unmarked normal state. Hidden states (draft/archived) get a quiet crossed-out-eye flag instead of colored badges; the Home feed says "new" instead of "published".
• "Shelved in" is now Drive-style folder chips (icon + folder name; ownership in the tooltip).
• Attachment upload is a designed dropzone (click or drag, auto-uploads); owner actions are consistent icon buttons; tags are edited as chips with suggestions.
• Liquid-glass visual refresh: gradient mesh backdrop with translucent, blurred panels (nav, cards, popovers, search, floating comment pill), gradient primary buttons, softer radii — light + dark.

Feedback round 2 (workspace as the landing surface)

• Workspace main pane mirrors your filing tree: collapsible groups per root folder (subtree rollup) plus "Unfiled", each with its own lazy pagination; group headings are drop targets (file a plan / nest a folder by dropping on them). Drafts are no longer a separate group — rows carry the quiet flag wherever they're filed.
• "Since you last looked" strip: plans updated since your last visit ("updated") or never opened and not yours ("new to you"), driven by per-viewer read tracking. Self-clears as you read.
• Nav is Workspace (landing) + Feed. Explainer copy removed throughout — the UI says it or it doesn't.
• One pen. The single edit icon opens the unified editor (title + tag chips + content). The separate title/tags page is gone (old route redirects). The floating comment navigator bar is deleted; keyboard nav (j/k/r/a/d, s for resolved) stays.
• Add-modal: references and attachments share one Popover-API lightbox pattern instead of always-visible inline forms.
• Folders: created inline in the sidebar (type a name, Enter), nested by dragging one folder onto another (PATCH /folders/:id, cycle/depth/library rules enforced by the model).
• Document types are visual: coplan_plan_types.icon (curated lucide set, per-install branding) renders as a leading chip on every row, feed item, and plan header.
• Mobile pass: nav collapses to icons, popovers/forms clamp to the viewport, workspace stacks main-pane-first.

Polish & audit round (design, testing depth, dead code, Rails 8/Stimulus idioms)

Three-agent audit (dead code, idioms, test gaps), findings triaged and applied:

• Visibility fix: the needs-attention strip now routes through Plan.visible_to + active — stale notifications can no longer resurface an archived plan or leak another user's draft title. Locked in with request specs.
• Service extraction: checkbox toggles go through a new Plans::ToggleCheckbox service instead of an inline copy of the versioning pipeline in the controller.
• Stimulus hygiene: comment-nav's advance-after-action observer is now single + timeboxed + cleaned up on disconnect (was stacking one per keypress); linked-thread retry timer cleared on disconnect; mention picker aborts stale searches; dead submitOnEnter action and unused targets/values removed.
• Query work: one grouped COUNT for all folder groups; one shared unread-notifications query per request; shelves sort in SQL; notifications index capped; pagination stopped issuing an extra COUNT.
• Rails 8 idioms: params.expect across web controllers (malformed payloads 400 instead of 500), normalizes for tag/folder names, atomic thread+first-comment create, new workspace_path helper replacing 15 hand-rolled params.permit(...).merge link sites.
• Dead code deleted: the line-selection feature (helper + controller, broken since the anchor-text system replaced it), orphaned dropdown component (JS + CSS), 8 unreferenced CSS blocks, brainstorm status tokens.
• A11y: add-modal gets aria-labelledby + autofocus, plan groups get aria-controls + true hidden when collapsed, inbox bell reports aria-expanded.
• New test coverage: PlanPolicy + visible_to/publicly_listed unit specs (the discovery predicate had none), the unified editor's metadata path incl. metadata surviving an edit conflict, recency-strip bounds, libraries/theme/llms/version-diff request specs, and browser specs for the search modal, inbox, theme switcher, tag chips, folder-drag reparenting, and modal close paths.

Verification

• Full suite: 1204 examples, 0 failures (isolated per-worktree test DB).
• Migration cycle verified: migrate → rollback → migrate clean on MySQL 8.
• Design QA: three screenshot passes (round 3: workspace folder groups, recency strip, add-modals, type chips, mobile 390px, dark mode)
• Previous rounds: two screenshot passes over Home, Workspace, Library, Profile, plan page (incl. draft state, attachments, edit form) and search in light + dark (seeded demo DB, port 4600); tag chip editor exercised in-browser.
• PRD updated to rev 7 to match implementation (born-published, unlisted drafts).

🤖 Generated with Claude Code

Feedback round 3 (Drive-style workspace + the 17-item list)

• The workspace is now one level at a time, like Drive/Dropbox Paper. Each level shows its subfolders (empty ones too — that's where you drop things) and the docs filed right there; the root shows your unfiled docs. There is no "Unfiled" pseudo-folder and no flattened subtree. Breadcrumbs (My Plans › Payments › EBT) replace the "Folder:" chip and are drop targets, so dragging up a level is a thing.
• Filters behave like search: picking a type/tag/date window switches to flat results scoped to the current folder's subtree. Every sidebar count now answers "what will clicking this show" given the other active filters — the #kmp (2) inside an empty folder bug is gone (tags/types with no matches drop out).
• Document types are file icons, not tag-looking chips: a colored file glyph (stable tint per type name, name in the tooltip) leads every row, the plan header, search results, home feed, and profiles. Types moved to the top of the filter sidebar; created/updated windows ("Last 7/30 days") joined it.
• "Since you last looked" now shows what changed: a new section-level markdown differ compares the version you last saw against the current one and the plan page highlights just those sections — once, per viewer; the visit that shows them also spends them. Back-nav can't resurrect the stale strip anymore (workspace opts out of Turbo's snapshot cache).
• Drag works wherever you grab the card (inner links no longer steal the drag payload), and rows drop onto sidebar folders, main-pane folder rows, and breadcrumb segments alike.
• New folder is a popover matching the references/attachments add-modals, pre-nested inside the folder you're viewing. (Also fixed it prefilling the current folder's own name.)
• Draft → "Private": quiet crossed-eye flag on cards/search/OG descriptions, "Publish" is now "Share with everyone", the sidebar's Hidden section has Private/Archived toggles, and the agent API describes visibility: "draft" as a rare, explicit-request-only escape hatch.
• Anyone signed in can add references and attachments (new contribute? policy — the upload UI no longer vanishes on plans you didn't write); removal stays with the author. The tab bar grew a shared "+" next to References and Attachments that activates the panel and opens its add-modal in one click — this also fixes the dead add-reference popup (popovers can't open from inside a hidden tab panel).
• Plan header tightened: icon + title + byline in one compact block; shelves and owner actions share one row.
• Mobile: the comment composer and thread popovers are full-width bottom sheets (the composer had to join the popover top layer — the glass panel's backdrop-filter made it the containing block, pinning the "fixed" sheet off-screen), and the workspace sidebar collapses behind a "Filters & folders" disclosure.
• Keyboard nav: j/k walk folders and docs, Enter opens, Backspace goes up a level, Esc clears filters.
• Tests: 1233 examples green, including new specs for the section differ, the once-only highlight semantics, Drive-level navigation/breadcrumbs/keyboard flows, folder-scoped counts, date windows, and the contribute policy. (System specs now run at an explicit 1400px viewport — the Capybara-registered headless-chrome driver silently ignores screen_size.)

Full-review pass (2fcbcb5)

A four-lens review of the whole diff (visibility/authz, correctness, JS/CSS, perf/tests), findings verified before fixing:

• Visibility: API folder counts and the reference typeahead were the only two discovery surfaces still counting archived plans — both now apply .active like everything else. Everything else checked clean: every list/search/feed/notification path routes through visible_to/listed?, and flash/toast output is escape-safe.
• Changed-section highlights got a real fix, not a patch: the server differ now sections the rendered document with the same Commonmarker options as the page, so fence toggles, setext/indented headings, CRLF bodies, HTML entities, and body-less headings can't desync server keys from client anchors (6 verified false-positive/false-negative classes, all covered by specs).
• Sidebar counts respect the Hidden filter — folder links carry ?filter=, so their counts now count what the click will show.
• Plans::Place hardening: unshelving is always allowed even if the plan has since become unlisted; concurrent double-shelving retries instead of 500ing. The service's guard rails (the web move endpoint's whole security boundary) now have a dedicated spec.
• JS honesty: dropping a doc on the folder it's already in is a no-op instead of a PATCH + reload + "Moved" toast; Enter/Backspace no longer hijack focused buttons/links; the mobile comment sheet and changed-section note survive Turbo's snapshot cache correctly.
• Perf: the workspace index was preloading full MEDIUMTEXT version bodies (content, diff, operations) for every row — it now preloads a lean id+sha stub and fetches the body only on preview-cache miss; search typeahead N+1 on plan types fixed.
• New tests: draft-shelving rejection over both JSON and HTML, web references contribute policy, folder-scoped page-2 pagination, Escape-key navigation. Full suite: 1255 examples, 0 failures.

Feedback round 4 (bookmarks, footnotes, the two-way eye)

• Saving is bookmarking, and it behaves like one. The flat "Add to Folder" select is gone everywhere. Rows and the plan page get a bookmark button: unsaved, it opens a folder navigator popover — the full hierarchy as a tree (like a filesystem) — to pick where it goes; saved, a second click just removes it, no dialog, no toast (the hover tint hints at it). Filing a plan places a pointer in your library; nothing is copied, and unbookmarking never touches the plan itself. Your own plans always live at My Plans root even when unfiled.
• No more tabs on the plan page. The document is followed by footnote sections for References and Attachments — visually quieter, anchored ([/] jump between document and footnotes), listed at the bottom of the table of contents with counts. Each footnote header has a round icon-only + that opens the existing add-popovers. History moved to its own page behind a clock icon in the header — Backspace (or the back arrow) returns to the document; old ?tab=history links redirect. The TOC toggle moved from ] to t.
• Show/hide is a two-way eye (author only, in the header): first click previews the flip — the slash appears/disappears and the button pulses; it reverts by itself after a few seconds if you wander off. Second click commits over fetch, no reload. Hiding takes a shared plan back to Private (unlisted, link keeps working); sharing works the same in reverse. Hides are logged in plan history like publishes.
• Sidebar reads as one tree: My Plans is the root node with your folders nested beneath it, and the sidebar's "+ New folder" is gone (the breadcrumb bar's New folder button remains — it nests where you're standing).
• Keyboard parity: arrow keys mirror j/k on the workspace; Backspace on a plan page takes you back to wherever you came from (falls back to the workspace when you arrived cold).
• Updated filters join the combinatorial-count contract: "Last 7/30 days" links now show counts computed under the other active filters and drop out when empty — same rule every other sidebar count already follows.
• Scale prep for 50k+ docs: three new indexes — a covering index for the per-folder placement counts and (author, updated_at) / (visibility, updated_at) on plans — keep the workspace queries index-only at that scale, no non-ActiveRecord machinery needed.
• Rows read like Drive rows: the type icon is full-height across both text lines; the row's ⋯ menu is replaced by the bookmark, which shows on hover/focus.
• Plan-type admin got its icon field: ActiveAdmin's PlanTypes form now offers the curated built-in icon set (tint stays derived from the type name).
• Sign-in no longer double-loads. The host layout tracked a different stylesheet than the engine layout, so Turbo force-reloaded the page on every sign-in/out crossing — a wasted full load for users, and the async reload raced the next navigation (the source of an intermittent system-spec failure). Both layouts now track the engine stylesheet; the sign-in page inherits the current design and the stale copy of the old design tokens is deleted.
• Test infra: system specs now run on Chrome for Testing (pinned major 150) provisioned by selenium-manager, instead of the system Chrome — on managed machines the system browser force-installs IT extensions into test profiles, and one of them intermittently opened a background tab that wedged Capybara's teardown (the long-standing "failed to close window in 20 seconds" flake, now root-caused and gone).

Merged main (post-#140), reconciled (7d10932)

Main moved while this branch was open — this merge adopts its new features and re-expresses their state language in this branch's visibility model:

• Link previews + Slack unfurls (Add provider-neutral link previews and Slack adapter #154): adopted. LinkPreviews.for_plan now builds its context as state · type · author where published is the unmarked state — only Private and Archived get a flag, and the word "Draft" never appears (matches the in-app language). OG descriptions and Slack unfurls share the one builder.
• Mermaid comment anchors (COPLAN-35: Keep Mermaid comments clickable #148/Fix clipped mermaid node labels by pinning label line-height #149/Expand Mermaid diagrams into a lightbox on click #151): adopted. The mermaid-settled re-highlight hook is wired into this branch's no-tabs plan page, and anchors-updated re-anchoring feeds the headless comment nav (the floating toolbar it targeted on main no longer exists). One behavior fix on top: clicking a comment mark inside a diagram now opens its thread popover instead of the lightbox — showModal() force-hides every open popover, so the lightbox was eating the popover the marks exist to open.
• Landing refresh + rendered agent-instructions page (Refresh public landing page and add rendered agent-instructions view #140): adopted. Step-1 copy and the hero mock now describe the born-published model (plans are listed from the start, or kept Private/unlisted); the mock's status badge became a plan-type badge.
• Status badge menu (Open the status menu from the plan's status badge #146): superseded. Visibility is the only state and the header eye toggles it; status_menu_controller is gone.
• Attachments dropzone (Style the attachments upload control #147): superseded by this branch's add-modal dropzone; its request specs were kept and reconciled to our selectors.

Full suite after the merge: 1301 examples, 0 failures.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 91cd5816fa

ℹ️ 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".

[chatgpt-codex-connector]

Allow folder-only API shelving by non-authors

This new placement path is still inside update, which returns 403 on !policy.update? before reaching Plans::Place. When a user tries to shelve someone else's published plan into their own library, the service would allow it via listed? and the web move_to_folder flow now supports it, but the API rejects the request just because the caller is not the plan author. Split folder-only updates from metadata authorization or let them reach Plans::Place while keeping title/visibility/tag edits author-only.

Useful? React with 👍 / 👎.

[HamptonMakes]

🤖 (replying on Hampton's behalf) Confirmed still valid — API update gates everything on PlanPolicy#update?, so a non-author can't shelve someone else's listed plan via the API even though the web move_to_folder flow (and Plans::Place itself) allows it. Deliberately deferring rather than special-casing folder-only PATCHes inside update: mixing two authorization regimes in one action is how policy bugs happen, and placements are viewer-relative anyway — they deserve their own endpoint (e.g. PUT /plans/:id/placement) that authorizes via Plans::Place's rules, mirroring the web route. Tracking as a follow-up after #153 lands.

[chatgpt-codex-connector]

Exclude archived plans from folder counts

Archived plans are excluded from /api/v1/plans by default, but these folder counts only apply visible_to and therefore still count archived placements. A folder containing only archived plans will report a positive plans_count while the default plan listing for that folder returns no plans, which also surfaces archived work on a default discovery endpoint. Apply the same active/non-archived predicate here (and in the single-folder serializer) so counts match the plans users can list.

Useful? React with 👍 / 👎.

[HamptonMakes]

🤖 (replying on Hampton's behalf) Already addressed — the full-review pass (2fcbcb5) applies .where(plan: Plan.active) in both places: the grouped index counts and the single-folder folder_json fallback count. Archived placements no longer inflate plans_count, so counts match what the default plan listing returns.

[chatgpt-codex-connector]

Do not report draft creation as a publish

When a plan is created as a draft and later published on a different day within the feed window, it is included in listed at build time, so this loop treats its revision-1 draft creation as a published activity; the PlanEvent query below then adds the real publish day too. Home can show a bogus publish entry (or two publish entries) for the same plan. Only plans actually born published should mark revision 1 this way.

Useful? React with 👍 / 👎.

[HamptonMakes]

🤖 (replying on Hampton's behalf) Valid — fixed in e8f355d. Revision 1 now counts as the publish moment only when the plan has no "published" event; born-draft plans get their publish day from the event alone, and their revision 1 (which predates being listed) no longer produces a feed item. Covered by new specs in spec/models/home_feed_spec.rb.