Editor Workspace & Callouts — Design

Status: implemented on main 2026-09-30 (not yet released). Canonical spec: docs/superpowers/specs/2026-09-30-editor-workspace-design.md; plan: docs/superpowers/plans/2026-09-30-editor-workspace.md. Part of the Wikantik Platform Development Hub. Follows the Editor Quality-of-Life design. Every item helps any editor of the wiki, and none changes the stored page format.

Problem

The editor now authors well, but navigating and structuring a knowledge base still feels unlike Obsidian:

• Ctrl-K opens full-text search only. There is no instant title switcher and no command palette.
• Links cannot be inspected or followed from the editor.
• New pages start from one generic stub, whatever their type.
• Nothing helps add links to existing pages while you write.
• Long pages cannot be folded by heading.
• Tags have no autocomplete.
• Clicking a sidebar link with unsaved changes leaves the editor without a warning.
• Obsidian's > [!note] callouts render as plain blockquotes.

Decisions

• One overlay:
  • Ctrl-K and Ctrl-O open a page switcher. Results are ranked by name, title and aliases:, with fuzzy matching, recent pages when the query is empty, and full-text results below.
  • Ctrl-P, or a leading >, switches the overlay to commands.
  • Rows at the bottom offer "search full text" and "create page".
• Commands:
  • One registry drives the palette, the toolbar and a / slash menu in the editor.
  • Editor commands exist only while the editor is open.
  • A shortcut the editor already handles (Ctrl-K inserts a link there) never also triggers a global action.
  • Editor commands apply their edits through the editor itself, so a keystroke typed right after a command is never lost.
• Link preview:
  • Hovering an internal link in the read view or the editor preview shows a small text-only card with title, type, cluster and summary or excerpt.
  • In the source editor, Ctrl/Cmd-hover shows the same card and Ctrl/Cmd-click opens the link in a new tab.
  • The preview endpoint returns the same 404 for missing and restricted pages, so it never reveals that a restricted page exists.
  • Cached previews are cleared when the signed-in user changes, and the endpoint is not cacheable across users.
• Templates:
  • Each page type (article, reference, design, runbook, hub) has a built-in template defined beside the frontmatter schema.
  • A test proves every template validates cleanly.
  • The new-page dialog offers all five types, with a preview of each template, and checks for an existing page on the server.
• Aliases: an optional aliases: frontmatter list, the same field Obsidian uses. The switcher and the mention scan match on it.
• Unlinked mentions (outgoing):
  • The editor rail lists phrases in the draft that match other pages' names, titles or aliases but are not yet linked.
  • Matching runs on the server against a title index, using the real Markdown parser, so code, headings and existing links are never matched.
  • Only pages the user can view are considered, before matching, so a restricted page can never hide a viewable one.
  • Link rewrites the phrase in your draft as one undoable edit; Ignore hides it for the session.
• Folding: headings and the frontmatter block fold in the editor. Any deliberate jump to a line inside a fold opens the fold first; passive scroll sync with the preview does not.
• Unsaved-changes guard: in-app links and switcher navigation ask before leaving a dirty editor. Links outside the app (attachments, static pages) load normally after "Leave without saving". The browser Back button is still covered by the local draft.
• Callouts:
  • Obsidian syntax and types, including foldable +/- variants rendered as <details>.
  • The server renderer and the editor preview produce identical HTML, checked against a shared test fixture.
  • Raw Markdown consumers are unaffected.

API changes

• GET /api/pages?q= ranks by title, alias and fuzzy match.
• New endpoints:
  • GET /api/pages/{name}/preview;
  • GET /api/page-templates;
  • POST /api/mentions/scan.
• No new configuration keys and no schema migration.

Out of scope

• Incoming unlinked mentions, which would edit other pages.
• Native [[Page]] stored syntax and embeds.
• Inline live preview.
• Saving fold state.
• Blocking the Back button.
• Templates editable as wiki pages.
• The rename follow-ups.