The Resources tab replaces task tracking. Its sidebar lists the current repository's artifacts by most recent update, selects the first by default, and renders Markdown. Tutorial artifacts hold a complete, self-contained HTML document instead of Markdown; they render in a sandboxed embedded view on macOS and open in the default browser elsewhere or on demand. Tutorials share the reader’s neutral theme, compact typography, and right-hand “On this page” outline. Their artifact options menu sits above that rail. They have no Markdown editor or comment UI, and comments are rejected for them. Selection remains stable across refreshes. Browse artifacts in the command palette provides a global view, including legacy artifacts that do not yet have a repository.
Use Edit Markdown to change a document and Save or Cancel. The right sidebar has On this page and Comments tabs. Right-click a rendered block and choose Comment on this block, or use its + button. A block is a paragraph, heading, list, table, blockquote, or code block. Select words within that block first and choose Comment on selected text to attach feedback to that exact source range. The editor opens in the Comments tab while the document stays visible. Selection comments store the original Markdown byte offsets, source lines, and selected quote. Without a mapped selection, comments attach to the whole block. The gutter and background indicate comments on the containing block; selecting across separate blocks is not supported.
Click a Markdown task checkbox to save its checked state directly. Checkbox changes use the same revision checks as document edits and keep the reader's scroll position. They are unavailable while a document or comment draft is open or a save is in progress.
The reader styles top-level GitHub-style callouts named NOTE, TIP,
IMPORTANT, WARNING, and CAUTION. Put the marker alone on the first line,
for example > [!NOTE], followed by quoted body lines. Callouts retain block
comment controls and their original Markdown source. Unknown names, nested
callouts and markers with a title on the same line remain ordinary blockquotes.
Saved blocks carry a background wash and a comment-count button: amber while comments are open, green once every comment on the block is resolved. Click the button to open the comment, or click a comment card's content to return to its block. Multiple comments on the same block remain separate cards. Each card's ⋯ menu contains Edit, Resolve / Reopen, and Delete. Add document comment retains the existing document-level feedback workflow. Use the artifact options menu's Copy Markdown to copy the whole source.
Block and selection anchors retain their original Markdown excerpt, optional selected quote, UTF-8 byte offsets, one-based source lines, and surrounding context. Unchanged excerpts can relocate after insertions or moves. Edits outside a selection can leave its anchor intact, even within the same paragraph. Edited, removed, or ambiguously repeated excerpts are marked Outdated and retain their original excerpt; their cards can still be edited, resolved, reopened, or deleted. Restoring an identifiable original block restores navigation. Resolved comments remain visible and can be reopened. Desktop polling picks up CLI changes. Comment mutations retain the artifact's revision checks, and conflicting saves keep the draft.
Originating sessions appear as links and open through the existing session navigator in their associated checkout. Missing sessions report an error without starting a different session.
Keyboard navigation (Cmd+J on macOS, Ctrl+J on Linux/Windows) offers m Edit Markdown and c Add comment for a selected Markdown resource, or w Save draft and q Cancel draft while drafting, alongside h/l pane movement. View-only resources expose neither row. See the keyboard reference.
The shared reader renders these links as inline references with local hover details. The author-supplied label remains visible and copyable:
[Backend](devcroft:repository/backend)
[Design](devcroft:artifact/art-23456789)
[Discussion](devcroft:session/backend/codex/native-session-id)Use real keys from devcroft repository list --json, artifact IDs from
devcroft artifact list --json, and provider/session IDs from
devcroft session list --json. Percent-encode session IDs as a URL path segment.
Session references support opencode, codex, claude, and Antigravity (agy).
They contain no checkout or provider-store paths. The repository binding
and session must be available on this device, and ambiguous matches are rejected.
Click or keyboard-activate a reference to open it. Artifact links open in global
Browse artifacts, including records outside the current
page or kind filter. Existing drafts are retained; an active draft in the
destination browser must be saved or cancelled first. To open a reference from
the CLI, use devcroft app --open-reference URL.
Hover metadata is read in the background for up to 128 unique references per document revision. Session details use the saved local catalog. These details may be older than the destination; opening rechecks availability. Missing references remain readable and explain failures. Use short labels for the atomic inline elements. Inline links are supported; reference-style Markdown definitions are not enriched. Ordinary web links remain ordinary links.
Projects, Resources, and recent-session views use shared empty states, with actions for adding repositories or clearing filters and the existing session creation control. Loading and failures remain separate from empty data.
Mermaid and math typesetting are not enabled. Future plugin candidates are source-file links, GitHub-style note/warning callouts, PR/issue hover cards, and optional math rendering.
portable/artifacts/<art-id>/artifact.md is the atomic record. Schema version 6 metadata is JSON (a YAML subset), enclosed by --- lines. The body follows the closing delimiter: Markdown for RFC, Plan, Note, and Review artifacts, or one complete self-contained HTML document for Tutorial artifacts. Tutorial content must not be empty, and records cannot change kind between the tutorial and Markdown formats. Metadata includes ID, title, kind, repository key, originating sessions, comments, and creation/update timestamps. Only plans and RFCs have a workflow status. Plans use Todo (default), In Progress, and Done; RFCs use To Review (default), Approved, and Implemented. Storage and JSON spell these todo, in_progress, done, to_review, approved, and implemented; CLI arguments use in-progress and to-review. Notes, reviews, and tutorials omit status and reject status mutations. Changing Markdown kind resets status to the new kind’s default, or removes it for kinds without a workflow; an explicit status must match the new kind. Schemas 3/4 map archived plans to Done and archived RFCs to Implemented, otherwise using the kind’s default. Schema 5’s shared statuses migrate by workflow stage for plans/RFCs and are removed from other kinds. Migration persists on the next write. Comments may have a tagged anchor with kind: "block"; older comments without an anchor remain document-level feedback. Comment metadata does not insert markers into the Markdown body. Unknown metadata round-trips unchanged.
App and CLI mutations share a portable gate and per-artifact lock. A hash of the complete file is the revision. Saves check the revision, write and sync a temporary file, then atomically rename it. Conflicts leave editor drafts intact. Files must be regular UTF-8 files, no symlinks, at most 4 MiB including metadata.
The reader applies presentation styles and in-page outline navigation to a display copy; the stored HTML is unchanged and the script has no host bridge. Opening a tutorial in the browser rewrites a disposable device-local copy under cache/tutorials/ in the data root; copies untouched for 30 days are pruned the next time a tutorial is opened, and the cache never syncs. Tutorial records use a kind value older Devcroft builds cannot parse: once a data root contains tutorials, use a current build for that root.
Existing schema 3 JSON artifacts are read without modification. The first explicit edit writes Markdown; old JSON is retained as a recovery copy, and Markdown takes precedence afterward. Unassociated artifacts remain available through Browse artifacts and can be assigned with artifact update --repository KEY. Old task records are left on disk but are no longer read or exposed by the application.
See the bundled agent resource instructions for creation, editing, session links, and the full comment lifecycle. All operations are headless. DEVCROFT_DATA_DIR selects the same root used by the desktop.
With an isolated data root and registered checkouts, create artifacts for two repositories. Open Resources and check filtering, ordering, default selection, Markdown rendering, long sidebar scrolling, and status filtering. Edit Markdown, cancel once, then save. Add block feedback with and without a selected quote, check both directions of navigation, and edit/delete through the card menu. Insert text before an anchor, then change its block and check the Outdated state. Add feedback in the desktop, read/resolve/reopen it with the CLI, and verify the polling update. Edit concurrently in the CLI and desktop and verify the desktop retains its draft after a conflict. Link sessions from both repositories and verify each opens the correct workspace. Create a tutorial artifact and check that it renders in the sandboxed viewer, offers no edit or comment controls, and opens in the browser from the artifact options menu. Check outline navigation and active-section highlighting, the matching rail/menu placement, and both light and dark themes. Check empty repositories, malformed records, and missing sessions. Mark plans through Todo, In Progress, and Done, and RFCs through To Review, Approved, and Implemented from the artifact options menu; confirm the sidebar and detail badges follow. Check that notes, reviews, and tutorials have no status badges or status actions, and that their kind filters hide the status filter. Switching between plan and RFC filters must clear an incompatible status filter.