Memos creation and resources
This is the implementation target, not a claim that the redesigned methods, flags or server guarantees are released. Code tabs compare the same intended action through each interface. Current behavior is called out separately. See the API index for migration boundaries.
List accessible Memos
Require an explicit namespace or a configured default. --namespace and --ns are source context everywhere. List with limit and zero-based row offset, not a page index. Do not store a shared current page on the client.
dl memos list --ns your-workspace --limit 20 --offset 0const page = await dl.notes.list({ namespace: "your-workspace", limit: 20, offset: 0 })page = dl.notes.list(namespace="your-workspace", limit=20, offset=0)notes_list({ namespace: "your-workspace", limit: 20, offset: 0 })Continue with offset 20, 40, and so on for pages of 20 under the defined response contract. Keep filters and ordering unchanged. The current frontend returns notes and total; final cross-interface continuation/end fields remain to specify. A short page alone is not a universal end-of-list guarantee. Return ready-to-use stable IDs, resolved namespace and URL where available.
Offset browsing can skip/duplicate resources under concurrent insertion, deletion or reordering. Parallel requests reduce elapsed time but do not guarantee a complete scan. A frozen complete scan needs a separately specified snapshot contract. No cursor migration is part of the consolidation. Search is a separate action.
Create an empty Memo
name and text are optional. Omitted text means exact empty source; proposed omitted-name display is Untitled. Default visibility is private. Namespace comes from an explicit argument or a configured default; fail clearly when neither exists.
dl memos create --ns your-workspaceconst note = await dl.notes.create({ namespace: "your-workspace" })
console.log(note.id)note = dl.notes.create(namespace="your-workspace")
print(note.id)notes_create({ namespace: "your-workspace" })SDKs return a usable Memo handle exposing the stable ID. Structured tool/CLI results include id, qualified ref, canonical url and acknowledged initial-source revision; include source hash when finalizing the receipt schema. Do not invent a source acknowledgment if only catalog creation succeeded.
TTY output should show the title, stable ID and a clickable canonical link, with plain URL fallback. A link never grants permission by itself.
Create with initial source
Every tab creates a Memo titled Review with exactly # Review followed by one LF.
printf '# Review\n' | dl memos create "Review" --ns your-workspace --file - --jsonconst note = await dl.notes.create({ namespace: "your-workspace", name: "Review", text: "# Review\n" })note = dl.notes.create(namespace="your-workspace", name="Review", text="# Review\n")notes_create({ namespace: "your-workspace", name: "Review", text: "# Review\n" })Creation plus source initialization must be atomic or expose partial completion with the created stable ID and recovery action. A lost response must not cause the caller to create a second Memo blindly. Existing Python create_note(text=...) uses a second legacy forced body write; current TS creates metadata. Those paths are not equivalent atomic creation. Replace that divergence during implementation.
Source input preserves Unicode, CRLF/LF and trailing-newline state. --file - explicitly consumes stdin; no body option means empty content, without waiting on piped input. See CLI streams.
Rename a Memo
Rename changes display name. Preserve stable ID and source/RTC history. Slug changes and redirect policy are separate decisions, not an undocumented side effect. No body RTC revision is required for a catalog rename; metadata concurrency needs its own resource version.
dl memos rename "$NOTE_ID" --name "New title"const result = await dl.notes(noteId).rename({ name: "New title" })result = dl.notes(note_id).rename(name="New title")notes_rename({ note: noteId, name: "New title" })A name-only move may delegate to this same rename implementation. A simple rename must not accidentally require an ownership transfer or change access. Return stable ID, resulting name and canonical URL. Collision/empty-name rules and concurrent rename preconditions remain to finalize.
Saved versions
Named immutable versions differ from retained RTC revisions. Listing versions, reading one, saving one and restoring it are distinct actions. The following names are proposed; Python helpers and shared receipt contracts are not yet verified as implemented.
dl note hist "$NOTE_ID" --ns your-workspace
dl note read "$NOTE_ID" --ns your-workspace --version "$VERSION_ID"const versions = await dl.notes(noteId).versions.list()
const saved = await dl.notes(noteId).versions.read({ versionId })versions = dl.notes(note_id).versions.list()
saved = dl.notes(note_id).versions.read(version_id=version_id)notes_versions_list({ note: noteId })
notes_versions_read({ note: noteId, versionId })Version reads return saved content and immutable version metadata, not a baseline for an unguarded current write. A restore must read current source and explicitly apply the saved target with conflict/recovery guarantees. Define retention, pagination, save preconditions and restore receipt before exposing new helpers. Do not equate durable watch catch-up with an archive of every intermediate version.
The CLI snippets here use target --ns; the installed command's current namespace flag remains authoritative until the alias ships.
Archive a Memo or folder
Archive is separate from deletion, sharing, tags and saved versions. The archive API contract documents the concrete HTTP operations, current CLI/TS/Python methods, registered built-in tools and query filters. These additions use the existing client interfaces; they do not imply that the broader handle redesign on this page has shipped.
An archived Memo retains its source, stable identity, attachments, project filings
and Bindr memberships. Active listings exclude archived items unless requested
with includeArchived; changed durable edits and explicit unarchive restore the
item and its valid live folder paths. Reads and unchanged saves do not.
Independently archived siblings and deleted items remain unchanged. Keep archive
changes as their own metadata operation; never encode archival as a delete or tag.
Delete a whole Memo
Reserve delete() for deleting the Memo resource. Remove deletes selected text instead. Do not use one ambiguous delete method for both. A final delete tool/CLI spelling, soft-delete/restore guarantees, ownership requirements and confirmation behavior remain to review; this page deliberately does not invent a callable mutation.
Delete must distinguish an accepted deletion from an unknown outcome. Never recreate a Memo to simulate recovery. Resolve current authority and stable identity before mutation; body revision and metadata permission are separate concerns.
Remaining resource families
The following need method-by-method review before publication as executable reference:
- Metadata summary/visibility: distinguish catalog properties from source; visibility and sharing are independent.
- Shares: granting, revoking, listing recipients and removing grants need explicit resource authorization and results; sharing success proves no body save.
- Project filing: clarify additional affiliations versus moving one existing filing. See multiple filings.
- Attachments: file identity, exact paths, conditional versions, collision behavior and byte upload/download receipts.
- Media: hosted URLs have different permission semantics from Memo attachments; do not silently substitute one for the other.
- Cross-Note file move/copy and resource restore: negotiate actual server capability, preserve operation identity, and report partial/unknown results honestly.
Current command inventory is not authority to mutate user resources. Once each contract is settled, add a four-interface example for the same action here or in its owning method-family page.