deepvista-notes

intent

deepvista-notes lets you create, read, update, and delete notes in your deepvista knowledge base. notes are markdown-backed knowledge cards tagged with type=note, designed for capturing explicit knowledge: meeting summaries, research, decisions, quick observations. trigger this skill when a user says "take a note", "save this", "show my notes", or asks to read/edit/delete a specific note by title or id. do not trigger for cross-note analysis (use deepvista-recipe-analyze-notes instead) or non-note card types.

inputs

prerequisite: deepvista-cli installed and authenticated. see deepvista-shared for auth setup, profile configuration, and global flags.

external connection:

• deepvista backend API (requires valid auth token, typically stored in ~/.deepvista/config or DEEPVISTA_TOKEN env var)
• app.deepvista.ai web interface (for displaying clickable note URLs post-write)

parameters (passed to deepvista notes commands):

• note_id: unique identifier returned by deepvista (e.g. note_abc123)
• title: string, max 255 chars (required for create, optional for update)
• content: markdown string, inline (use for short content only, < 500 chars)
• content-file: path to markdown file or - for stdin (required for files, URLs, or content > 500 chars)
• tags: json array of strings, e.g. ["meeting","urgent"] (optional)
• limit: integer, max notes to return (default 20, max 100)
• page: integer, pagination offset (default 1)

edge cases to handle:

• auth token expired: skill must catch auth errors and prompt re-auth via deepvista-shared
• rate limits: deepvista API may return 429; implement exponential backoff (1s, 2s, 4s) up to 3 retries
• network timeout: if curl/http call exceeds 30s, fail gracefully and report timeout to user
• empty result set: list or search returns no notes; report "no notes found" rather than crashing
• file not found: if --content-file path does not exist, error before executing command
• malformed json (tags): validate json syntax before passing to cli
• stdin pipe failure: if piping from curl/cat fails mid-stream, catch and report
• very large files: files > 50mb should warn user before upload; suggest chunking

procedure

step 1: validate user intent and inputs

input: user request (natural language or explicit command)

action: parse the user's intent. determine which subcommand to run (list, get, create, update, delete, +quick). extract parameters (note_id, title, content, file path, tags). validate that required parameters are present for the chosen subcommand.

output: validated intent (subcommand name), parameters dict, confirmation status (does user need to approve before execution?)

edge case handling:

• if user provides both --content and --content-file, warn user that --content-file takes precedence
• if title is empty or missing for create/update, reprompt user
• if note_id is invalid format, ask user to clarify

step 2: check if write operation requires confirmation

input: subcommand from step 1

action: write operations (create, update, delete, +quick) require explicit user confirmation before execution. read operations (list, get) do not.

output: confirmation status (boolean), confirmation prompt (if needed)

step 3: handle file input for content

input: content-file parameter (if provided), content parameter (if provided)

action:

• if content-file is provided and not -, check that the file exists locally. if not, error and stop.
• if content-file is -, prepare to read from stdin (e.g. curl output).
• if content-file is a local path, read the full file into memory. validate file size (warn if > 50mb).
• if only --content is provided (inline), use it directly (for short content).
• if neither is provided and create command requires content, reprompt user.

output: resolved content (string or stdin stream), content source (inline, file path, or stdin)

edge case handling:

• file encoding: assume utf-8. if file is binary or non-utf8, error.
• stdin timeout: if reading from pipe exceeds 30s, timeout and fail.
• file path with spaces: quote properly in shell invocation.

step 4: build and execute deepvista command

input: validated subcommand, parameters, content (from step 3), confirmation (from step 2)

action:

• if write operation and user did not confirm in step 2, stop and do not execute.
• construct the full deepvista cli command string with all flags and parameters.
• escape quotes and special chars in title/content appropriately for shell.
• execute command via shell (e.g. subprocess.run() or equivalent).
• capture stdout and stderr.
• handle exit codes: 0 is success, 1 is generic error, 401 is auth fail, 429 is rate limit, others map to user-facing errors.

output: command execution result (exit code, stdout json, stderr message)

edge case handling:

• auth error (401): catch and report "auth token expired or invalid. re-run deepvista login".
• rate limit (429): retry up to 3 times with backoff (1s, 2s, 4s).
• timeout: if command hangs > 30s, kill process and report timeout.
• invalid json response: if stdout is not valid json, report "deepvista api returned malformed response".

step 5: extract response data and construct output

input: command execution result from step 4

action:

• parse json response from stdout.
• for create/update/delete: extract the note id and any metadata (timestamps, url).
• for list: extract array of notes (id, title, created_at, updated_at, tags).
• for get: extract full note object (id, title, content, tags, created_at, updated_at).
• for +quick: extract the created note id.
• construct the app.deepvista.ai url: https://app.deepvista.ai/notes/<id>.

output: structured response object (note id, title, content snippet, url, timestamp), formatted for display

edge case handling:

• missing id in response: log warning, still return response body to user.
• list with 0 results: return empty list message rather than error.
• very long content: truncate display to 500 chars in list view, show full in get view.

step 6: present result to user

input: structured response from step 5

action:

• for write operations: display "note created/updated/deleted" + clickable url + note id.
• for read operations: display note content, metadata (title, tags, timestamps), formatted as markdown or structured text.
• for list: show table or bullet list of notes with titles, ids, created_at, tag summary.
• for errors: display clear error message (e.g. "note not found", "auth failed", "rate limited").

output: user-facing message, formatted for readability

decision points

decision: should this be a write operation confirmation or a read operation?

• if subcommand is list, get, or +search: read-only, no confirmation needed.
• if subcommand is create, update, delete, or +quick: write operation, require explicit user confirmation before execution.

decision: should content come from inline string, file, or stdin?

• if user provides --content-file <path>: read from local file (validate file exists first).
• if user provides --content-file -: read from stdin (e.g. curl output).
• if user provides only --content "...": use inline string (appropriate for short content < 500 chars).
• if user provides both --content and --content-file: --content-file takes precedence; warn user.
• if none provided and command is create: reprompt user for content.

decision: is this a file import, URL import, or manual note entry?

• if user says "import", "upload", "save this file", or provides a file path: treat as file import, use --content-file <path>.
• if user provides a url: download the file first (curl), then use --content-file <path>.
• if user manually types or pastes content: use --content for short text (< 500 chars) or write to temp file and use --content-file for longer content.
• never summarize or paraphrase imported content; store the exact text as provided.

decision: has the auth token expired or is the user not authenticated?

• if deepvista command returns 401: report "authentication failed" and instruct user to run deepvista login (see deepvista-shared).
• if DEEPVISTA_TOKEN env var is not set and no local config exists: report "not authenticated" and guide user to deepvista-shared setup.
• else: proceed with command.

decision: has the api rate limit been hit?

• if deepvista returns 429 (too many requests): implement exponential backoff. retry after 1s, then 2s, then 4s (up to 3 total attempts).
• if all 3 retries fail: report "rate limited. try again in a few moments" and do not retry further.
• else: proceed normally.

decision: is the note content larger than practical for inline passing?

• if content size > 500 chars or content is a file: use --content-file (read from disk or stdin).
• if content size <= 500 chars and is user-provided text: use --content inline.
• rationale: agent context windows and shell argument limits make large inline content unreliable; file-based input guarantees exact content preservation.

decision: should the user see the full note content or a preview?

• for list command: show title, id, tags, and first 100 chars of content (preview).
• for get command: show full note content, all metadata.
• for create/update output: show title, id, url (full content already shown in confirmation step).

output contract

on success (create, update, +quick):

• http 200/201 response with json body containing note object
• note object schema: {id: string, title: string, content: string, type: "note", tags: [string], created_at: timestamp, updated_at: timestamp}
• output format: plain text message with note url (https://app.deepvista.ai/notes/{id}) presented as clickable link
• example: Note created: My Meeting (note_abc123)\nView: https://app.deepvista.ai/notes/note_abc123

on success (get):

• http 200 response with json body containing full note object
• output format: markdown-formatted note content, with metadata header (title, id, tags, timestamps)
• example:

  # My Meeting (note_abc123)
  Tags: meeting, standup
  Created: 2026-03-26T10:00:00Z
  Updated: 2026-03-26T11:00:00Z
  
  ## Discussion
  - Roadmap priorities
  - CLI release
  

on success (list):

• http 200 response with json body containing array of note objects
• output format: table or bullet list with columns/fields: title, id, tags, created_at
• example:

  # Your Notes (5 total)
  
  1. Standup 2026-03-26 (note_abc)
     Tags: standup, weekly | Created: 2026-03-26
  
  2. Architecture review (note_def)
     Tags: architecture, design | Created: 2026-03-25
  

on success (delete):

• http 200/204 response, typically empty body or minimal confirmation json
• output format: plain text confirmation
• example: Note deleted: My Meeting (note_abc123)

on success (importing a file or url):

• http 200/201 response with created note object
• file content stored verbatim in note.content field (no summarization, no truncation)
• note url displayed with clickable link

on error:

• http error code (400, 401, 404, 429, 500, timeout)
• error message from deepvista api (or timeout/network error message)
• output format: plain text error description, user-friendly
• examples:
  • Error: Note not found (note_xyz123) (404)
  • Error: Authentication failed. Run 'deepvista login' to reconnect. (401)
  • Error: Rate limited. Please try again in a few moments. (429)
  • Error: Network timeout. Check your connection and try again. (timeout)
  • Error: Invalid tags format. Must be valid JSON array. (400)

file location for note content: notes are stored in deepvista backend (not on disk). after creation, user can view the note at https://app.deepvista.ai/notes/{id} or retrieve via deepvista notes get {id}.

outcome signal

the skill has worked when:

1. create, update, +quick: user sees success message with note title, id, and clickable deepvista app url. user can then open the url and confirm the note appears in the web ui with correct title, content, tags, and timestamps.

2. get: user sees the full note displayed in the terminal with all content, metadata, and formatting intact.

3. list: user sees a table or list of notes with titles, ids, and tags. user can identify the note they are looking for or confirm "no notes found" if list is empty.

4. delete: user sees confirmation message that the note has been deleted. attempting to deepvista notes get {id} afterward returns 404 (not found).

5. import (file or url): user sees success message with note url. user opens the url and confirms the note contains the exact content from the imported file or url (no paraphrasing, no truncation). if the file was > 1mb, user may have received a size warning beforehand but the import succeeded anyway.

6. error handling: if auth fails, user sees clear message and instructions to re-run deepvista login. if rate limited, user sees message to retry later (and retry is attempted automatically up to 3 times). if network timeout, user sees timeout message and is instructed to check connection. if file not found, user sees error before any api call is made.