Shubo · Roadmap

Snapshot of ROADMAP.md · 2026-06-17 · the markdown is canonical (regenerate after edits)
file-based Linear · DIRECTION / DESIGN / FEAT / ROADMAP / HELP
▶ To decide what's next, read this board — the Now cycle + the ranked backlog — and open a single FEAT- only when it's the in-flight one. Never read every FEAT to choose (that's how focus is lost). Closed FEATs archive, so the board stays a short list of in-flight work — a focused board, not a pile of stale tickets.
Now — current cycle
▶ FOUNDATION · personal-first

Light up personal library → read papers + cited writing

The first personal-first research workspace foundation — useful with zero AI, zero collab/billing.

Feature☑ Foundation scopeStatus
reference-managerSource truth · Library search/listing · full-text availability · import target · read/cite anchorShipped · foundation substrate
import door.bib import into citeable Source truthShipped · .bib door
paper-readeropen a Library PDF in a large branded reader · highlight/note/jumpback · usr private / org workspace layers + creator attributionShipped · Read v1 + Mark v2 (M0–M3)
note-editorproduction Note CRUD · basic location/move · structured TipTap body · save/reopen · generic slash commandsBuilding · backend merged #361 · FE editor in review #240
note-citations/cite from Library · citation nodes · live References · CSL/style framework + switchNext · style framework pinned
Foundation read loop: sign up → .bib import or existing Library source has available full text → open the Library paper in Paper Reader Read v1 → the PDF is readable in a large branded reader with honest unavailable states.
Foundation write/cite loop: sign up → .bib import works → Library rows with CSL truth are visible/searchable → create a note → write in the production editor → /cite Library papers → generated References section updates → switch style → save/reopen. No AI call is required.
Critical-path planning bar: only the MVP slices that block this Foundation loop need to be plan-ready now. Good non-critical subfeatures stay in deferred candidates with priority, or in explicitly non-blocking parallel tracks.
Paper Reader Read v1 is Foundation Shipped · Read v1 Mark v2 M0–M3 shipped — uploading/importing references is not enough; the user must be able to open and read the paper. Read v1 validated reading; Mark v2 (highlight → note → jumpback + usr private / org workspace layers + creator attribution) shipped on the merged Source access gate (#271): frontend #137/#138 + backend #322. Only the M4 chat/citation clickback consumer remains.
‖ Parallel track (@pinglin) · Dynamic Organization M0–M5 core built — Shubo's context-routing system for agents: governed metadata scopes, associative recall, and evidence anchors so agents can find relevant context with fewer tokens. M0/M1/M2/M3/M4/M5 are built or live-proven in the markdown board; M6–M8 continue behind data-gated and consumer-contract work. Folders stay user-owned; Shubo labels and scopes, it never re-files content.
Not in Foundation acceptance: full onboarding route ①/③ · add your work · PDF upload/import · making RIS/CSL-JSON a blocker beyond the .bib door · RM AI-index bridge · First Warm Library Ask · warm chips · Zotero/deep connectors · Grounded AI Write · Paper Reader Mark v2 · Dynamic Organization M1-M8 · all Share Era features · billing. Parallel work must not block Foundation.
Backlog — ranked, foundation before leaves

FOUNDATION non-AI cited writing

Free to validate. The user can complete writing without any AI call.

1Reference Library
Shipped · foundation substrate
now, the root — R0/R1 landed; full-text availability + listing + OA landed; Library/import affordance + export + arXiv enrich shipped in #127/#203; AI-index bridge is Grounded Assist, not Foundation
Import/export shipped#127 / #203 mergedLater · AI-index bridge
Pull 5Gate 5Effort 3Rev 5
2Note Editor
Building · backend merged
can build in parallel with import — production notes, CRUD, basic location/move, TipTap editor, generic slash commands; no sharing UX
Backend CRUD/body/move/revision/ACL ✓ #361FE editor in review #2407 design ADRs
Pull 4Gate 4Effort 4Rev 5
blocks Note Citations, Grounded AI Write, Submission Export, Manuscript Review
3Import Door
Shipped · .bib door
narrow onboarding slice — .bib Foundation door shipped; RIS/CSL-JSON + DOI/arXiv input ride the same parser/import path; PDF upload/import and route ①/③/add-your-work later
Route ② shipped#127 / #203 merged
Pull 5Gate 4Effort 4Rev 5
depends on reference-manager Source truth; does not block Note Editor
4Note Citations
Next
after Note Editor + Import Door/RM — /cite a Library paper → live reference list → CSL/style framework + style switch; the non-AI writing bicycle
Style framework acceptance pinned
Pull 5Gate 5Effort 3Rev 4
depends on Note Editor + reference-manager; CSL/style proof can de-risk in parallel but cannot ship first
5Paper Reader
Shipped · Read v1 + Mark v2 (M0–M3)
parallel — Read v1 opens a Library PDF in a large branded reader; Mark v2 highlight → note → jumpback + usr private / org workspace layers + creator attribution shipped (frontend #137/#138 + backend #322 on merged Source access gate #271)
Read v1 shippedMark v2 M0–M3 shippedM4 clickback later
Pull 5Gate 4Effort 3Rev 4
does not block non-AI cited writing
6Source Access Foundation
Next · Foundation hardening
reusable Source access gate — generalize the annotation-access slice shipped via #271/#322 into one can_read / can_update / can_delete_source boundary every Source consumer calls; personal-ns + org/library semantics
Annotation slice shipped #271/#322Plan-ready draft
Pull 4Gate 5Effort 4Rev 5
blocks Paper Reader Mark v2 endpoints · Source-backed citations · grounded fragments — they must not invent Source ACLs
7Grounded AI Write
Grounded Assist · needs design pass
Grounded Assist — after Note Editor + Note Citations + RM AI-index/RAG + Dynamic Organization context routing; AI suggestions emit citation nodes; first AI command contract is not plan-ready
Not plan ready
Pull 5Gate 5Effort 2Rev 4
depends on Note Editor + Note Citations + RM AI-index/RAG + Dynamic Organization context-routing consumer contract
8Submission Export
Manuscript Finish · design pinned
Manuscript Finish — after Note Citations; cited note/draft → docx/LaTeX/venue handoff
Pull 4Gate 3Effort 2Rev 3
depends on Note Editor + Note Citations (cited note/draft model)
9Manuscript Review
Manuscript Finish · design pinned
Manuscript Finish — after Grounded AI Write; claim/citation audit (unsupported claims, weak evidence, misattribution)
Pull 4Gate 3Effort 2Rev 4
depends on Note Citations + Grounded AI Write (a cited note/draft + source provenance)
10Dynamic Organization
Building · context routing
context-routing system for agents: consolidates unstructured content + long-term memory into metadata scopes, associative recall, and evidence anchors so agents find relevant context with fewer tokens; folders stay user-owned
M0–M5 builtM2 smart foldersM3 autonomy completeM4 scope + RM facetsM5 tunnelsM6–M8 laterGrounded Write dep ratified
Pull 4Gate 4Effort 2Rev 4
depends on reference-manager + Import Door (a populated library) · provides the Grounded AI Write context-routing substrate · obeys DESIGN-faceted-organization
11First Warm Library Ask
Next · activation
activation/RAG proof after Import Door + RM full-text Part 2/R3 — readiness rollup, manual Library Ask, source fragments, and scope disclosure
Plan ready · Slice 1Slice 2 chips later
Pull 3Gate 2Effort 3Rev 5
good-to-have for onboarding activation; not the writing spine
12Full Onboarding
Building · later acquisition
route ① OpenAlex/ORCID claim → My work shipped; route ③ topic and add-your-work later
Pull 3Gate 2Effort 3Rev 5
not a Foundation blocker; the narrow Import Door owns cited-writing entry

SHARE ERA collaboration layer

Gated after personal-first is complete. Share verbs unlock these.

13Real-time Collaboration
Next · designed
when share lands — the collaboration base (Hocuspocus + Yjs)
Pull 3Gate 5Effort 3Rev 5
depends on personal-first complete
14Comments
Next · designed
right after collab — "share to comment", anchors free from Yjs
Pull 4Gate 3Effort 4Rev 5
depends on collaboration (Yjs anchor layer)
15Notification Center
Next · designed
with comment — mention/reply triggers; self-built center + Sonner toast
Pull 3Gate 3Effort 4Rev 5
depends on collaboration (event source)
Deferred candidates — good subfeatures, not Foundation blockers

Large features compress to a minimal MVP first. Useful subfeatures outside that MVP stay visible here with priority, instead of bloating the active acceptance bar. They do not need full implementation planning until they enter a critical path or a ranked slot.

High · Folder Home / Folder Overview
After Note Editor, give each Folder exactly one singleton overview document that reuses the Note editor/body/save model but is not listed, moved, or deleted as a normal Note.
High · Quick Search must be Source-aware
Quick Search indexes files/folders/chats, but the shubo unit is the Source (a Source layers over a File; a not-yet-RAG'd Source has no File). So Sources without full text never surface, and the bento open-mapping opens a file result as a source panel by file id → useGetSource 404s. Search/return Sources keyed by source_id (title/author/venue), opening the Library row + Paper Reader. Shubo-only — not in instill. Surfaced by the bento navigation audit (frontend-shubo #240).
Medium · AI assistance disclosure statement
Jenni-parity after AI writing/editing exists: Note editor command that inserts a short editable paragraph naming Shubo, the broad assistance type, and author review/responsibility; no separate surface, provenance ledger, AI detection, or journal-policy engine in v1.
Medium · Bento Box workspace shell
Define one scene model for left rail, middle work panel, right context/Ask panel, expanded scenes, resize handles, collapse/hover/pin behavior, URL/state preservation, surface/elevation tokens, and shared panel top bars.
Medium · PDF upload/import
After Foundation, accept user PDFs. First design metadata/cite-truth extraction, duplicate handling, attachment pairing, and failure UX.
Low · Node.js Active LTS upgrade
Move frontend from node 20.x to the current Active LTS line, currently 24.x; do not target 26.x while it is still Current. Update engines, CI/dev images, setup docs, and verify build/tests/storybook/token generation.
Low · bioRxiv / medRxiv URLs
Parse canonical preprint URLs into DOI form; keep DOI/arXiv as the Foundation path.
Low · metadata refresh action
Add an explicit refresh path for verified-but-stale rows; preserve source id, user edits, full text, indexing, highlights, and notes.
Low · parser module hardening
After shared import lands, keep parser logic isolated and deepen malformed, partial, BibTeX/RIS/CSL-JSON, CJK, LaTeX, and large-file fixtures.
Low · arXiv subject projection
Capture arXiv category/subjects for future filters or discovery without adding user-facing tags or expanding the Foundation bar.
Dependency map — blockers and parallel work (no time scale)
Foundation writing path — follow the arrows
Already cleared: RM core + Import Door. They stay in the lanes below as context; Note Editor is the next Foundation writing blocker.
Import Door
citeable Source truth
+
Note Editor
base writer
→
Note Citations
cited-writing payoff
Import Door is now cleared. Note Editor can build next; Note Citations is where notes and citeable Library Source truth merge. AI-index and Library Ask are activation/RAG work below; they do not block the non-AI cited-writing bicycle.
Reference Librarynon-AI core · root
RM corecleared
Import Doorneeds RM
.bib importcleared
Note Editorbase writer
notes + slashparallel
Note Citationsneeds Notes + RM
/cite + refsmerge
RM AI-index Bridgeactivation/RAG
AI-index bridgeAI layer
First Warm Library Askactivation
manual Library Askgood-to-have
Paper Readerneeds RM full text
Read + Mark ✓shipped
Dynamic Organization‖ parallel · @pinglin
Dyn Org context routingparallel
Grounded AI Writeneeds citations + RAG
AI draft + citesneeds plan
Submission Exportneeds Note Citations
docx / LaTeX
Manuscript Reviewneeds grounded write
claim / citation audit
personal-first complete · share verbs unlock
Collaborationafter personal-first
Collaboration
Commentsneeds collab
Comments
Notificationneeds collab
Notification
 Cleared prerequisite  Current Foundation writing blocker  Writing payoff target  Parallel · not blocking Foundation  Later planned personal feature  Needs design pass · not plan-ready  Share Era ← left = dependency depth, not time
Status — just three (keep PM simple)
Next→ Building→ Shipped→ archive/ · closed
Next = queued (raw idea → fully-designed; readiness shows in the FEAT's own filled sections). Building = being built now (the active named stage). Shipped = a user can actually do the thing — that, not a green backend, is the bar; only Shipped triggers a help article (R7). Design-done and code-green (e.g. RM's R0) are Scope ☑ facts inside the FEAT, never board states. A finished FEAT closes to archive/ (self-labeled Shipped ✓) with the repo's docs/ + help/ as its living record. The board shows only: what's shipped, what's building, what's next.
System map — five concepts (frame → work → outward truth)

Two former "layers" were cut to stay simple: archive/ is a state (Retired), not a doc type — see Status above; and inward "how it works" is not a planning prefix — it lives in each repo's docs/ / docs/invariants/ next to the code (the quality gate), so planning owns only the outward help/.

LayerPrefix / fileManagesTime
VisionDIRECTION-why we exist / where to gorarely changes
DesignDESIGN-cross-feature laws a FEAT obeysrevised, never ships
FeatureFEAT-<name>one buildable unit (+ Scope ☑/☐)ships complete
BoardROADMAP.mdranking + Now + disciplinealways rolling
Help (outward)help/ · MkDocswhat a user can do today · en/zh-Hans/zh-Hant · on shiptracks shipped
Discipline — R1–R7 (the system stays alive)
R1 · discovery before creation
Discuss a feature → first check it's in a FEAT; if not, create one + register in ROADMAP. A conclusion that stays in chat didn't happen.
R2 · single source of truth
A decision/scope lives in one doc (its FEAT/DESIGN); ROADMAP only references.
R3 · status freshness
Code lands → mark the FEAT ☑→✓, update status, roll Now. A board that lies is worse than none.
R4 · stage rolling
Active stage end-to-end green → check the next ☐ batch → roll Now to the next named stage. One cycle at a time.
MVP compression
Big feature → name the smallest useful MVP in Now; move good-but-not-now subfeatures to backlog with high / medium / low priority.
Critical-path planning
Only MVP slices blocking the active loop must be plan-ready. Other subfeatures stay backlog, parallel, or later-stage until they compete for a ranked slot.
Next FEAT planning
For planning-only work, scope + acceptance/QA + dependencies are enough. Backend/frontend implementation sections may stay deferred until Building.
R5 · prefix / extract-DESIGN + archive-on-close
Hit a decision bigger than the feature (constrains others) → extract a DESIGN the FEAT references. Two things archive: dropped/superseded (✗) and fully-closed FEATs (✓, once the repo docs/ + help/ exist). The bloat valve — the live board shows only in-flight work.
R6 · no BUG-/IMPROVEMENT-
Improvement = a ☐ item or a new FEAT; a bug worth fixing is just fixed.
R7 · HELP on ship
When a user-facing feature ships: confirm the repo's docs/invariants reflect it (inward — already required by the quality gate) + write the help-center article (outward, en/zh-Hans/zh-Hant) from the user's POV. Tracks shipped reality — never pre-written from the roadmap.
⚙ enforced by
the shubo-planning skill — fires whenever a feature/scope is discussed.