MetaList 0.12.0__tar.gz → 0.13.0__tar.gz

{metalist-0.12.0 → metalist-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metalist
-Version: 0.12.0
+Version: 0.13.0
 Summary: A minimalist single-user note-taking app with SSR, fast in-memory tree operations, and efficient sync.
 Project-URL: Homepage, https://github.com/evolvingstuff/metalist
 Project-URL: Repository, https://github.com/evolvingstuff/metalist
@@ -49,6 +49,14 @@ A minimalist single-user note-taking app focused on server-side rendering (SSR),
 - Multi-tab search contexts with server-persisted scroll/search state (survives browser restarts)
 - Manual namespace backups/restores to a user-selected backup folder with retention controls
 
+## Changes in 0.13.0
+
+- Dictation: text from speech-to-text tools such as Superwhisper, pasted into the search bar or any tag field, becomes your existing tags ("neural network" gives `neural-network`). Say "quote … end quote" for text, "minus" to exclude, "at" before meta tags such as `@todo`. In a note, the words after "start tags" go to its tag bar. The phrases are set in Dictation Settings, and one undo restores what was pasted.
+- A quoted search with a space at its edge matches whole words: `" fat"` no longer finds "father".
+- The AI keeps a record of what it did for each answer (notes read, searches, web pages opened), so questions like "did you search the web for that?" are answered from what actually happened.
+- Dropping a `.txt`, `.md`, `.csv` or `.json` file stores it as before and adds its text as a child note, shown as Markdown, a table or formatted JSON. File pills show the extension (`.MD`, `.CSV`, …), and hovering a pill says that clicking downloads the file.
+- Typing one letter in the tag bar now narrows the suggestions you were already shown instead of reordering them, so the tag you want is in the top five far more often.
+
 ## Changes in 0.12.0
 
 - AI chat is now a tool-using agent: in one answer it can look up MetaList help, read and search the notes in your view, open web pages, and open menus, instead of picking a single route up front. Answers cite notes and web pages with clickable references, including each item listed from a web page.

{metalist-0.12.0 → metalist-0.13.0}/README.md

@@ -12,6 +12,14 @@ A minimalist single-user note-taking app focused on server-side rendering (SSR),
 - Multi-tab search contexts with server-persisted scroll/search state (survives browser restarts)
 - Manual namespace backups/restores to a user-selected backup folder with retention controls
 
+## Changes in 0.13.0
+
+- Dictation: text from speech-to-text tools such as Superwhisper, pasted into the search bar or any tag field, becomes your existing tags ("neural network" gives `neural-network`). Say "quote … end quote" for text, "minus" to exclude, "at" before meta tags such as `@todo`. In a note, the words after "start tags" go to its tag bar. The phrases are set in Dictation Settings, and one undo restores what was pasted.
+- A quoted search with a space at its edge matches whole words: `" fat"` no longer finds "father".
+- The AI keeps a record of what it did for each answer (notes read, searches, web pages opened), so questions like "did you search the web for that?" are answered from what actually happened.
+- Dropping a `.txt`, `.md`, `.csv` or `.json` file stores it as before and adds its text as a child note, shown as Markdown, a table or formatted JSON. File pills show the extension (`.MD`, `.CSV`, …), and hovering a pill says that clicking downloads the file.
+- Typing one letter in the tag bar now narrows the suggestions you were already shown instead of reordering them, so the tag you want is in the top five far more often.
+
 ## Changes in 0.12.0
 
 - AI chat is now a tool-using agent: in one answer it can look up MetaList help, read and search the notes in your view, open web pages, and open menus, instead of picking a single route up front. Answers cite notes and web pages with clickable references, including each item listed from a web page.

{metalist-0.12.0 → metalist-0.13.0}/app/api/note_requests.py

@@ -106,6 +106,18 @@ class SearchSuggestionInteractionRequest(TypedDict):
 class TabSearchInteractionRequest(TypedDict):
     searchQuery: Text
 
+@with_config(ConfigDict(strict=True))
+class DictationPasteRequest(TypedDict):
+    """Text pasted into the search bar or the tag bar, and the field's current value."""
+    text: Text
+    target: Literal["search", "tags", "tag", "condition"]
+    current_value: Text
+    # The spoken phrases around a quoted phrase (Dictation Settings).
+    quote_open: Identifier
+    quote_close: Identifier
+    # Spoken before a search term to exclude it (Dictation Settings).
+    negate_phrase: Identifier
+
 @with_config(ConfigDict(strict=True))
 class TagSuggestionsRequest(TypedDict):
     note_id: Identifier
@@ -136,6 +148,14 @@ class CreateChildRequest(TypedDict):
     undoContext: UndoContext
     viewport: Viewport
 
+@with_config(ConfigDict(strict=True))
+class CreateFilePreviewChildRequest(TypedDict):
+    fileId: Identifier
+    search_query: Text | None
+    clientId: Identifier
+    undoContext: UndoContext
+    viewport: Viewport
+
 @with_config(ConfigDict(strict=True))
 class UpdateNoteRequest(TypedDict):
     clientId: Identifier

{metalist-0.12.0 → metalist-0.13.0}/app/api/routes/ai.py

@@ -642,6 +642,7 @@ def stream_ai_chat(
         model=payload.model,
     )
     provider_messages = ai_chat_store.provider_messages(session_key=session_key)
+    earlier_actions = ai_chat_store.earlier_actions(session_key=session_key)
     initial_messages = agent_context_builder.build_initial_messages(
         canonical_messages=provider_messages,
         prompts=prompts,
@@ -654,7 +655,7 @@ def stream_ai_chat(
     events = _stream_runtime_events(payload=payload, openai_api_key=openai_api_key,
         session_key=session_key, provider_messages=provider_messages, prompts=prompts, skills=skills,
         retrieval_settings=retrieval_settings, frozen_scope=frozen_scope, tagging_run=tagging_run,
-        web_settings=web_settings,
+        web_settings=web_settings, earlier_actions=earlier_actions,
         initial_input_tokens=initial_approx_input_tokens)
 
     return StreamingResponse(
@@ -673,6 +674,7 @@ async def _stream_runtime_events(
     provider_messages: list[dict[str, str]], prompts: AgentPromptSet, skills: AgentSkillSet,
     retrieval_settings: AgentRetrievalSettings, frozen_scope: ScopedSearchSnapshot,
     tagging_run: TaggingRun, initial_input_tokens: int, web_settings: AgentWebSettings,
+    earlier_actions: list[dict[str, object]],
 ) -> AsyncIterator[dict[str, object]]:
     action, start_label = 'provider_runtime', 'Connecting to OpenAI API'
     ready_label = 'OpenAI API ready · 1,050,000-token context'
@@ -686,7 +688,7 @@ async def _stream_runtime_events(
             selected_model=payload.model, thinking_level=payload.thinking_level,
             canonical_messages=provider_messages, prompts=prompts, skills=skills,
             retrieval_settings=retrieval_settings, web_settings=web_settings,
-            frozen_scope=frozen_scope, tagging_run=tagging_run)
+            frozen_scope=frozen_scope, tagging_run=tagging_run, earlier_actions=earlier_actions)
     try:
         async for event in events:
             yield event

{metalist-0.12.0 → metalist-0.13.0}/app/api/routes/notes.py

@@ -20,9 +20,11 @@ from app.api.note_requests import (
     SearchSuggestionInteractionRequest,
     TabSearchInteractionRequest,
     TagSuggestionsRequest,
+    DictationPasteRequest,
     CreateNoteTopRequest,
     CreateSiblingRequest,
     CreateChildRequest,
+    CreateFilePreviewChildRequest,
     UpdateNoteRequest,
     SaveNoteRequest,
     AddSelectedTextTagRequest,
@@ -61,7 +63,9 @@ from app.services.exception_capture import CapturedExceptionContext
 from app.usecases.create_note import CmdCreateNote
 from app.usecases.base import QueryCommand
 from app.usecases.create_sibling import CmdCreateSibling
+from app.services.file_registry import file_registry
 from app.usecases.create_child import CmdCreateChild
+from app.usecases.create_file_preview_child import CmdCreateFilePreviewChild
 from app.usecases.update_content import CmdUpdateContent
 from app.usecases.prefetch_link_titles import CmdPrefetchLinkTitles
 from app.usecases.add_selected_text_tag import CmdAddSelectedTextTag
@@ -127,6 +131,7 @@ from app.services.html_export import build_notes_export_filename
 from app.services.note_fullscreen import build_note_fullscreen_markup
 from app.services.link_titles import link_title_store
 from app.services.search_index import search_index
+from app.services.dictation_cleanup import clean_dictated_paste
 from app.services.tag_suggestions import suggest_tags_for_note
 from app.services.undo_state import reset_undo_stack
 from app.usecases.prioritize import list_prioritize_tag_suggestions
@@ -551,6 +556,22 @@ def delete_tag_interactions(request: Request) -> Dict[str, object]:
     return {"deletedCount": deleted_count}
 
 
+@router.post("/notes/dictation-paste")
+@transactional_route
+def dictation_paste(payload: DictationPasteRequest) -> Dict[str, object]:
+    """Read-only: the cleaned-up text to insert for a paste (docs/ui/dictation-paste.md)."""
+    text = clean_dictated_paste(
+        text=payload["text"],
+        target=payload["target"],
+        existing_tag_frequencies=search_index.list_explicit_tag_frequencies(),
+        current_value=payload["current_value"],
+        quote_open=payload["quote_open"],
+        quote_close=payload["quote_close"],
+        negate_phrase=payload["negate_phrase"],
+    )
+    return {"text": text}
+
+
 @router.post("/notes/tag-suggestions")
 @transactional_route
 def tag_suggestions(payload: TagSuggestionsRequest) -> Dict[str, object]:
@@ -750,6 +771,27 @@ def create_child(request: Request, note_id: str, body: CreateChildRequest):
     return cmd.execute()
 
 
+@router.post("/notes/file-preview-child/{note_id}")
+@transactional_route
+def create_file_preview_child(request: Request, note_id: str, body: CreateFilePreviewChildRequest):
+    token = _require_bearer_token(request)
+    viewport = _require_viewport(body)
+    _require_note_present(note_id, context="notes.file-preview-child")
+    file_id = body["fileId"]
+    if not file_registry.has_file(file_id):
+        raise HTTPException(status_code=404, detail=f"File not found: {file_id}")
+    cmd = CmdCreateFilePreviewChild(
+        parent_note_id=note_id,
+        file_id=file_id,
+        search_query=body["search_query"],
+        token=token,
+        client_id=body["clientId"],
+        undo_context=body["undoContext"],
+        viewport=viewport,
+    )
+    return cmd.execute()
+
+
 @router.put("/notes/{note_id}")
 @transactional_route
 def update_note(request: Request, note_id: str, body: UpdateNoteRequest):

metalist-0.13.0/app/services/agent/action_log.py

@@ -0,0 +1,59 @@
+"""The agent's own record of what it did for an answer.
+
+Each tool call becomes one short entry: what was asked and what came of it,
+never the content a tool returned (page text and notes can be huge, and the
+model can read them again). The entries are kept with the answer for the rest of
+the chat and given to the model on later turns, so a question such as "did you
+search the web for that?" is answered from what actually happened. Only the
+model sees them.
+"""
+
+from __future__ import annotations
+
+import json
+
+
+_NOTE_READ_TOOLS = frozenset({"read_view_notes", "search_view_notes"})
+_OPERATION_TOOLS = frozenset({"summarize_view", "propose_tag_generation", "propose_tag_review"})
+_KNOWN_TOOLS = _NOTE_READ_TOOLS | _OPERATION_TOOLS | {
+    "lookup_metalist_help", "view_overview", "open_web_pages", "open_menu",
+}
+
+
+def describe_action(*, name: str, arguments: str, result_content: str, is_error: bool) -> dict[str, object]:
+    """One log entry for a tool call, from its JSON arguments and JSON result."""
+    # A rejected call may name a tool that does not exist: it is still recorded.
+    if is_error:
+        return {"tool": name, "rejected": True}
+    if name not in _KNOWN_TOOLS:
+        raise ValueError(f"No action log entry for unknown tool: {name!r}")
+    parsed_arguments = json.loads(arguments)
+    assert isinstance(parsed_arguments, dict), "Tool arguments are a JSON object"
+    if name in _OPERATION_TOOLS:
+        return {"tool": name, "arguments": parsed_arguments}
+    result = json.loads(result_content)
+    assert isinstance(result, dict), "Tool results are a JSON object"
+    if name == "lookup_metalist_help":
+        return {"tool": name, "topics": list(parsed_arguments["topics"])}
+    if name == "view_overview":
+        return {"tool": name, "notes_in_view": result["note_count"], "trees_in_view": result["tree_count"]}
+    if name == "open_menu":
+        return {"tool": name, "menu": result["label"], "status": result["status"]}
+    if name == "open_web_pages":
+        return {"tool": name, "pages": [_page_entry(page) for page in result["pages"]]}
+    entry: dict[str, object] = {"tool": name}
+    if name == "search_view_notes":
+        entry["query"] = parsed_arguments["query"]
+        entry["matching_notes"] = result["matching_note_count"]
+    entry["trees_read"] = len(result["trees"])
+    entry["trees_left_unread"] = len(result["unread_root_ids"])
+    entry["trees_too_large"] = len(result["too_large_root_ids"])
+    return entry
+
+
+def _page_entry(page: dict[str, object]) -> dict[str, object]:
+    """The address as asked, whether it opened, and its title when it did."""
+    title = ""
+    if page["status"] == "ok":
+        title = page["title"]
+    return {"url": page["requested_url"], "status": page["status"], "title": title}

{metalist-0.12.0 → metalist-0.13.0}/app/services/agent/agent_loop.py

@@ -52,6 +52,7 @@ from app.services.bulk_operation import bulk_operation_guard
 from app.services.agent.citation_tokens import ShortCitationTranslator
 from app.services.agent.note_aliases import NoteAliases
 from app.services.agent.execution_errors import AgentExecutionError
+from app.services.agent.action_log import describe_action
 
 
 MAX_AGENT_TURNS = 8
@@ -82,6 +83,8 @@ class AgentLoopState:
         self.web_evidence: list[WebPageEvidence] = []
         self.capabilities = capabilities
         self.content = ""
+        # What this answer did, for later turns (action_log.py).
+        self.actions: list[dict[str, object]] = []
         # Note text shown to the model, and full-mode addresses the user approved.
         self.note_text_parts: list[str] = [selected_note_text]
         self.approved_urls: set[str] = set()
@@ -129,14 +132,19 @@ class AgentLoopState:
                 "reference_note_ids": list(self.reference_note_ids),
                 "reference_web_ids": self.reference_web_ids()}
 
+    def record_action(self, *, call: dict[str, str], result_content: str, is_error: bool) -> None:
+        self.actions.append(describe_action(name=call["name"], arguments=call["arguments"],
+                                            result_content=result_content, is_error=is_error))
+
     def done_event(self) -> dict[str, object]:
         return {"type": "done", "reference_note_ids": list(self.reference_note_ids),
-                "reference_web_ids": self.reference_web_ids()}
+                "reference_web_ids": self.reference_web_ids(), "actions": list(self.actions)}
 
 
 class AgentLoopMixin:
     async def _run_agent_loop(
         self, *, run, canonical_messages: list[dict[str, str]], frozen_scope: ScopedSearchSnapshot, tagging_run,
+        earlier_actions: list[dict[str, object]],
     ) -> AsyncIterator[dict[str, object]]:
         if not isinstance(frozen_scope, ScopedSearchSnapshot):
             raise TypeError("frozen_scope must be ScopedSearchSnapshot")
@@ -167,6 +175,7 @@ class AgentLoopMixin:
         messages = self._context_builder.build_agent_messages(
             canonical_messages=canonical_messages, skills=run.skills, web_settings=run.web_settings,
             snapshot=snapshot, available_urls=capabilities.normalized_urls, note_aliases=note_aliases,
+            earlier_actions=earlier_actions,
         )
         self._trace_store.append_event(
             session_key=run.session_key, run_id=run.run_id, event_type="FROZEN_SCOPE",
@@ -238,16 +247,21 @@ class AgentLoopMixin:
                     result = tool_message_result({"summary": "not started",
                                                   "reason": "The current view has no notes to summarize."})
                     self._record_tool_call(run=run, call=operation, result_text=result.content)
+                    state.record_action(call=operation, result_content=result.content, is_error=False)
                     messages.append({"role": "tool", "tool_call_id": operation["id"], "name": operation["name"],
                                      "content": result.content})
                     answered_without_operation = True
                 elif not isinstance(parsed, ToolResult):
                     self._record_tool_call(run=run, call=operation, result_text="(operation started)")
+                    state.record_action(call=operation, result_content="{}", is_error=False)
                     async with aclosing(self._stream_agent_operation(
                         run=run, canonical_messages=canonical_messages, snapshot=snapshot,
                         tagging_run=tagging_run, arguments=parsed, state=state,
                     )) as operation_events:
                         async for event in operation_events:
+                            # The operation ends the answer: its completion carries the log.
+                            if event["type"] == "done":
+                                event = {**event, "actions": list(state.actions)}
                             yield event
                     return
             if answered_without_operation:
@@ -266,6 +280,7 @@ class AgentLoopMixin:
                 result = result_holder[0]
                 results.append(result)
                 state.add_tool_result(result)
+                state.record_action(call=call, result_content=result.content, is_error=result.is_error)
                 self._record_tool_call(run=run, call=call, result_text=result.content)
                 messages.append({"role": "tool", "tool_call_id": call["id"], "name": call["name"],
                                  "content": result.content})

{metalist-0.12.0 → metalist-0.13.0}/app/services/agent/context.py

@@ -78,7 +78,8 @@ class AgentContextBuilder:
             "none": (
                 "Web access is disabled. You cannot search or open pages. If the "
                 "request requires the web, state that limitation and tell the user "
-                "they can enable contextual or full web access in AI Agent Settings."
+                "they can enable contextual or full web access in AI Agent Settings. Label "
+                "anything you suggest from your own knowledge as not looked up."
             ),
             "contextual": (
                 "You may open only exact URLs in available_urls, plus addresses written in "
@@ -86,7 +87,11 @@ class AgentContextBuilder:
                 "A #fragment is ignored "
                 "when comparing, so https://a.example/page#part is the same address as "
                 "https://a.example/page. You cannot search, and links discovered inside "
-                "opened pages do not become available."
+                "opened pages do not become available. When a request needs a search (for "
+                "example newer or recent papers, releases or news), say plainly that this mode "
+                "only opens links already in the notes or chat, that 'Open any public web page' "
+                "in AI Agent Settings allows searching, and label anything you suggest from your "
+                "own knowledge as not looked up."
             ),
             "full": (
                 "You may open any direct public HTTP(S) page, including Google "
@@ -158,6 +163,7 @@ class AgentContextBuilder:
         snapshot: ScopedSearchSnapshot,
         available_urls: tuple[str, ...],
         note_aliases: NoteAliases,
+        earlier_actions: list[dict[str, object]],
     ) -> list[dict[str, object]]:
         """The tool-using agent's opening conversation.
 
@@ -189,6 +195,16 @@ class AgentContextBuilder:
             {"role": "user", "content": "SELECTED_NOTE_CONTEXT\n" + json.dumps(view_context, sort_keys=True, separators=(",", ":"))},
             *self.append_web_access_context(messages=[], settings=web_settings, available_urls=available_urls),
         ]
+        if earlier_actions:
+            context_messages.append({"role": "user", "content": "EARLIER_ACTIONS\n" + json.dumps({
+                "instruction": (
+                    "Your own record of what you did for each earlier answer in this chat, oldest first: "
+                    "the tools you called, what you asked for, and what came of them (page text and note "
+                    "content are not repeated here). Answer questions about how an earlier answer was made "
+                    "only from this record. If it does not show something, say you cannot tell."
+                ),
+                "answers": earlier_actions,
+            }, sort_keys=True, separators=(",", ":"))})
         return [
             *system_messages,
             *[dict(message) for message in canonical_messages[:-1]],

{metalist-0.12.0 → metalist-0.13.0}/app/services/agent/help_catalog.py

@@ -16,6 +16,7 @@ HELP_TOPICS = {
     'ai': ('AI and tag proposals', 'OpenAI settings, context limits, prompts/skills, history export, and AI tag proposals: generation, acceptance, rejection/removal and bulk undo limits. This topic alone covers proposal workflow explanations.'),
     'privacy': ('Privacy and security', 'Cloud disclosure, gray notes when hovering chat, password exclusion, encryption and credentials.'),
     'data': ('Namespaces and backups', 'Namespaces, backup/restore, HTML export, ports and updates.'),
+    'dictation': ('Dictation (speech to text)', 'Pasting dictated text from speech-to-text tools such as Superwhisper into the search bar, tag bar or a note: how words become tags, spoken dash/quote/or/not, "at to do" meta tags, the "start tags" phrase in notes, undo, and Dictation Settings.'),
     'releases': ('Release notes', 'What changed in each MetaList version (what is new, when a feature or fix arrived).'),
 }
 HelpTopic = Literal[tuple(HELP_TOPICS)]

{metalist-0.12.0 → metalist-0.13.0}/app/services/agent/prompts/agent.md

@@ -103,6 +103,13 @@ last tool call. Answer the user's exact current question. Use the conversation t
 resolve follow-ups such as "try again"; earlier answers are not evidence about the
 current view, and earlier citations must not be reused.
 
+`EARLIER_ACTIONS` is your own record of what you did for each earlier answer in
+this chat: the tools you called and what came of them. When asked how an earlier
+answer was made (did you search the web, which pages, did you read the notes),
+answer from that record, including the searches and pages it lists. If the record
+does not show something, say you cannot tell; never deny or claim an action
+otherwise.
+
 Notes are identified by short ids such as `n12`. Cite every claim drawn from a note
 with its id in double brackets, copying the `note_id` of the note whose
 `content_text` supports it (a child, not merely its root), directly after the

{metalist-0.12.0 → metalist-0.13.0}/app/services/agent/runtime.py

@@ -160,8 +160,12 @@ class AgentRuntime(AgentLoopMixin):
         web_settings: AgentWebSettings,
         frozen_scope: ScopedSearchSnapshot,
         tagging_run,
+        earlier_actions: list[dict[str, object]],
     ) -> AsyncIterator[dict[str, object]]:
-        """Answer with the tool-using agent loop (see agent_loop.py)."""
+        """Answer with the tool-using agent loop (see agent_loop.py).
+
+        `earlier_actions` is the agent's own record of what each earlier answer in
+        the history did (AiChatSessionStore.earlier_actions, action_log.py)."""
         run, _initial_messages = self._start_run(
             session_key=session_key, base_url=base_url, selected_model=selected_model,
             thinking_level=thinking_level, canonical_messages=canonical_messages, prompts=prompts,
@@ -172,7 +176,7 @@ class AgentRuntime(AgentLoopMixin):
             try:
                 async with aclosing(self._run_agent_loop(
                     run=run, canonical_messages=canonical_messages, frozen_scope=frozen_scope,
-                    tagging_run=tagging_run,
+                    tagging_run=tagging_run, earlier_actions=earlier_actions,
                 )) as steps:
                     async for event in steps:
                         self._trace_store.append_event(

{metalist-0.12.0 → metalist-0.13.0}/app/services/agent/skills/help-ai.md

@@ -39,7 +39,7 @@ a word search (every word must appear in a note's text or tags), and reading who
 result trees in visible order. Each read returns as many whole trees as fit the
 evidence limit; a tree is never divided, trees left unread can be read in a later
 step, and a tree too large for the limit on its own is reported instead of read.
-Notes within returned trees are complete. A whole-view summary packs trees in
+The AI keeps a private record of what it did for each answer in the chat (help it looked up, notes it read, searches and pages it opened), so it can say truthfully how an earlier answer was made; the record is cleared with the chat. Notes within returned trees are complete. A whole-view summary packs trees in
 visible order and asks before using several batches. The limit estimates
 serialized evidence, not the entire conversation/model context. Raising it can
 include more evidence and increase cost. A reference-source view

metalist-0.13.0/app/services/agent/skills/help-dictation.md

@@ -0,0 +1,92 @@
+# Dictation (speech to text)
+
+Use this reference to explain MetaList accurately. It describes user capabilities,
+not permission or tools for you to execute every operation. You can answer and
+request one supported menu/dialog opening. You cannot submit a form, change
+settings, run a shell command, or mutate notes through this help response. Do not
+claim that you inspected current notes or settings: none are supplied here.
+Prefer user-facing steps over implementation details. If the reference does not
+answer a question, say what is unknown; do not invent syntax or controls.
+
+Sources: docs/ui/dictation-paste.md
+
+## What it is for
+
+Speech-to-text tools such as Superwhisper paste sentences, not tags: saying
+"neural network" can arrive as `Neural network, neural network. Neural-Dash
+Network.` MetaList cleans up such text when it is **pasted** into the search bar, a
+note's tag bar, or a note being edited, and turns it into the user's tags. It uses
+fixed rules, no AI, and it only reacts to pasting: typed text is never changed.
+
+## How dictated words become tags
+
+- Sentence punctuation (`, . ? ! ; :`) is dropped.
+- Spoken joiners join words: "dash" or "hyphen" gives `-`, "underscore" `_`,
+  "slash" `/`. Superwhisper's `foo-Dash bar` gives `foo-bar`.
+- The longest run of words matching one of the user's existing tags becomes that
+  tag, ignoring capitals and treating spaces, `-`, `_`, `.` and `/` alike, spelled
+  the way the user uses it most. "neural network" gives `neural-network`.
+- Words also match a tag written as one word: "to do" gives `todo`, "scratch pad"
+  gives `scratchpad`.
+- "at" before the name of a built-in meta tag gives that meta tag: "at to do" gives
+  `@todo`, "at done" `@done`, "at list bulleted" `@list-bulleted`. Otherwise "at"
+  is ignored. One "at" covers a run of meta tags: "at green bold" gives
+  `@green @bold` (Superwhisper drops a repeated "at" anyway), even if the user also
+  has a plain tag such as `bold`.
+- "quote … end quote" (the default quote phrases) or quote marks mark a phrase, in
+  the search bar and tag relationship conditions only; in tag fields the quote
+  phrases are dropped.
+- Filler words (a, an, and, at, the, tag, tags, comma, period, um, uh) are ignored,
+  unless the word is itself one of the user's tags. A spoken word that is a tag
+  always stays that tag.
+- Repeats count once, and tags already in the field are not added again.
+
+## Where to paste
+
+- **Search bar:** words matching no tag are dropped. "or" becomes `OR`, the
+  exclusion phrase ("minus" by default) excludes the next term ("neural network
+  minus python" gives `neural-network -python`), and a quoted phrase becomes a text
+  search. "not" is an ordinary word unless it is set as the exclusion phrase.
+- **Tag bar:** words matching no tag become new tags, lowercased unless they look
+  like an acronym (`GPT`). Each word is its own tag unless the words together match
+  one of the user's tags; a new multi-word tag has to be typed.
+- **Other one-tag fields** (Edit Tag Relationships' search box, Add tag, Implied
+  tag, Synonym tag, Rename tag; Prioritize Tag; Manage tag proposals' tag filter):
+  the whole paste becomes one tag, "Machine learning" gives `machine-learning`.
+- **Tag relationship conditions:** existing tags and quoted text; no regular
+  expressions by voice.
+- **AI privacy tag lists:** tags, one per line.
+- **A note being edited:** say the tag phrase, **"start tags"** by default, then the
+  tags. The text before the phrase goes into the note; the words after it are added
+  to the note's tags with the tag-bar rules. "Here is my content. Start tags. Neural
+  network, at to do." adds the content and the tags `neural-network @todo`. Saying
+  only "Start tags, scratch pad." adds just the tag. Only the first phrase counts.
+  Words that together match no existing tag become separate tags: "spring planning"
+  gives `spring` and `planning`, never `spring-planning` (type a new multi-word tag).
+  Without the phrase, a paste into a note is an ordinary paste.
+
+It is a phrase rather than a repeated word because Superwhisper drops a word said
+twice in a row.
+
+## Undo
+
+One undo (Cmd/Ctrl+Z) right after the paste brings back what was pasted in the
+search bar or tag bar (in the tag bar without commas, which tags cannot contain).
+After a paste into a note, one undo removes both the pasted text and the added tags.
+
+## Dictation Settings
+
+The command palette's **Dictation Settings** dialog sets four phrases, each words of
+letters (2 to 64 characters): the phrase that starts tags in a note ("start tags"),
+the phrases that start and end a quote ("quote", "end quote"), and the phrase that
+excludes the next search term ("minus"). One unusual word such as "armadillo" also
+works. The quote and exclusion phrases must differ. Save applies them.
+
+## Tips and limits
+
+- Plurals do not match: "transformers" is not the tag `transformer`. In search it
+  is dropped; in the tag bar it becomes a new tag.
+- In the tag bar, a new multi-word tag has to be typed: dictated words become
+  separate tags unless together they match an existing tag.
+- Saying "dash" in its ordinary sense ("100 meter dash") joins the words around it.
+- `@size=…` and other values cannot be dictated; type them.

{metalist-0.12.0 → metalist-0.13.0}/app/services/agent/skills/help-menus.md

@@ -62,6 +62,7 @@ Opening or dismissing the command palette does not clear undo/redo. Global actio
 - Endpoint definitions (behavior/labels) live in code.
 - Palette preferences (`pref.*`) and command usage history are persisted per namespace in the main SQLite DB via `/api2/auth/client-state*`, not in browser `localStorage`.
 - `Animated transitions` is on by default and controls UI motion such as tag-bar edit transitions and note expand/collapse transitions.
+- `Dictation Settings` sets the spoken phrases for pasted dictated text: the phrase that starts tags in a note (`start tags`), the phrases that start and end a quote (`quote`, `end quote`), and the phrase that excludes the next search term (`minus`). Each is words of letters, 2 to 64 characters; the quote and exclusion phrases must differ. Save applies them, Escape or a click outside closes without saving.
 - `Visual Cues` opens one window of independent checkboxes, all on by default and saved immediately. Under Drag and drop: `Drag ghost` (a dashed outline of the dragged note and its visible children follows the pointer), `Drop indicator` (a grey landing line plus a faint outline on the note it lands beside or under), and `Direction cursor` (the mouse cursor itself becomes an up, down, indent or outdent icon for a possible move; impossible moves and the option turned off keep the usual grabbing hand). They change only what is shown; dragging works the same. Close the window with Escape or by clicking outside it.
 - `Note Layout & Appearance` stores namespace-scoped presets for top-level note size, child indentation, vertical spacing, note corners, and tag style. The defaults are `Larger`, `Standard`, `Comfortable`, `Round`, and `Pills` respectively. Note corners can be `Subtle`, `Rounded`, or `Round`; tag style shows visible note tags as outlined `Pills` or `Plain text` in both themes.
 - `Search suggestion stats & settings` is the single suggestion-personalization control surface. Its ordered 1–365 day slots and default-on time-window-label and one-credit-per-note-per-search-context toggles save immediately when changed. The modal also displays retained daily tag-credit statistics and provides the confirmed activity reset. An empty slot list disables personalization; the default slots are 1, 7, and 30 days.

{metalist-0.12.0 → metalist-0.13.0}/app/services/agent/skills/help-notes.md

@@ -39,6 +39,7 @@ Sources: docs/ui/controls.md
 | `⇧ + ⌘ + Z` or `⌘ + Y` | Redo text/tag edits locally, or redo the latest saved mutation when the active editor has no local edit history |
 
 - If note clipboard conditions are **not** met and edit mode is active, `⌘ + V` uses browser clipboard paste and runs external HTML sanitization before insertion.
+- Dictated text pasted into a note can end with tags: everything after the phrase "start tags" (set in `Dictation Settings`) is added to the note's tags. The full rules are in the dictation help topic.
 - When note paste replaces an empty target, the target keeps its search-context tags and merges in copied root tags with case-insensitive dedupe.
 - A saved whole-note paste resets the local editor history baseline so the next Undo reaches application history.
 - If the clipboard value came from `Generate random password…`, pasting into an empty note also adds `@password` automatically when that tag is not already present.

{metalist-0.12.0 → metalist-0.13.0}/app/services/agent/skills/help-references.md

@@ -36,12 +36,12 @@ Sources: docs/ui/references.md
     - when that compact source preview is a standalone URL with a cached link title, it displays the same `title · domain` treatment as the source note instead of the raw URL. Inline/prose URLs remain raw.
     - right-click anywhere inside a rendered reference and choose **Go to Source** to open that source note with the same navigation behavior.
   - File targets:
-    - non-image files render a file card/link row with a deterministic type badge (`PDF`, `IMG`, `VID`, `TXT`, etc.) and the file title.
+    - non-image files render a file card/link row with a deterministic type badge (`PDF`, `IMG`, `VID`, `TXT`, etc.) and the file title. `.txt`, `.md`, `.csv` and `.json` files are labelled by their extension: `.TXT`, `.MD`, `.CSV`, `.JSON`.
     - embedded image files (`![[UUID]]`) render an authenticated image preview with a `download image` control beneath it.
     - right-clicking the rendered image preview also offers image actions (`Copy Image`, `Save Image`, `Zoom Image`, `Open Image in New Tab`).
     - link-mode image files (`[[UUID]]`) keep the generic compact file card/link row.
     - embedded Excalidraw diagrams (`.excalidraw` files, badge `DRAW`) render their stored light or dark SVG preview; double-click or right-click **Edit Diagram** to open the full-screen editor (see Excalidraw Diagrams below).
-    - clicking the rendered file reference downloads the decrypted file from the server.
+    - clicking the rendered file reference downloads the decrypted file from the server; hovering it shows the tooltip "Click to download <file name>".
     - when the host note is collapsed, non-image file references stay visible as a single compact row showing the badge and a truncated title.
     - when the host note is collapsed and the first visible line is an embedded image file or diagram, the note collapses to a compact thumbnail-only version of that preview.
   - Rendered references have no internal expand/collapse or embed/link controls; edit the raw token to change between `![[...]]` and `[[...]]`.
@@ -60,6 +60,7 @@ Sources: docs/ui/references.md
 - Drag/drop follows the same attachment path for non-image files.
   - Dropping onto the actively edited note inserts into that note.
   - Dropping anywhere else creates a new top note first, then inserts there.
+- Dropping a `.txt`, `.md`, `.csv` or `.json` file also copies its text into a new child note under the note holding its pill, shown expanded. Markdown is tagged `@markdown`, CSV `@csv` and JSON `@json`, so they render as formatted text, a table and pretty-printed JSON. The child is the last child, one per file in drop order. It is an ordinary note: edit or delete it freely; the stored file is unchanged and clicking the pill still downloads it. Files over 200 KB or not in UTF-8 get only the pill, with a banner saying why. `Attach file…` adds no child.
 - Named image files dropped or pasted into the editor prompt for one of two paths:
   - `Paste Inline`: embed the image into note HTML as compressed `data:image/...`.
   - `Save as File`: upload the original file without recompression and insert its `![[UUID]]` token.

{metalist-0.12.0 → metalist-0.13.0}/app/services/agent/skills/help-releases.md

@@ -5,6 +5,14 @@ README. Changes made after the newest listed version are not described here.
 Compare with installed_version from the help lookup to tell the user whether
 they already have a release. Version info offers updates (see the data topic).
 
+## 0.13.0
+
+- Dictation: text from speech-to-text tools such as Superwhisper, pasted into the search bar or any tag field, becomes your existing tags ("neural network" gives `neural-network`). Say "quote … end quote" for text, "minus" to exclude, "at" before meta tags such as `@todo`. In a note, the words after "start tags" go to its tag bar. The phrases are set in Dictation Settings, and one undo restores what was pasted.
+- A quoted search with a space at its edge matches whole words: `" fat"` no longer finds "father".
+- The AI keeps a record of what it did for each answer (notes read, searches, web pages opened), so questions like "did you search the web for that?" are answered from what actually happened.
+- Dropping a `.txt`, `.md`, `.csv` or `.json` file stores it as before and adds its text as a child note, shown as Markdown, a table or formatted JSON. File pills show the extension (`.MD`, `.CSV`, …), and hovering a pill says that clicking downloads the file.
+- Typing one letter in the tag bar now narrows the suggestions you were already shown instead of reordering them, so the tag you want is in the top five far more often.
+
 ## 0.12.0
 
 - AI chat is now a tool-using agent: in one answer it can look up MetaList help, read and search the notes in your view, open web pages, and open menus, instead of picking a single route up front. Answers cite notes and web pages with clickable references, including each item listed from a web page.

{metalist-0.12.0 → metalist-0.13.0}/app/services/agent/skills/help-search.md

@@ -71,6 +71,9 @@ Searching for quote characters without escaping:
 - Leading/trailing whitespace is trimmed.
 - The verifier actively rewrites the input while typing (cursor/selection is preserved).
 
+## Pasting Dictated Text
+- Pasting (never typing) dictated text, for example from Superwhisper, turns it into tags: "neural network minus python" becomes `neural-network -python`. The full rules are in the dictation help topic.
+
 ## Completeness + Warnings
 The verifier produces:
 - `normalizedText`: the normalized query string.
@@ -135,6 +138,7 @@ Ontology rules also add **inferred tags** before search matching:
 - Prefix matching happens against the complete candidate set before the visible suggestion limit is applied, so an interacted `shortcut` cannot be discarded merely because 50 unrelated tags rank above it globally and leave frequency-ranked `short-story` first.
 - Case-equivalent tags are collapsed in suggestions, and the most-used spelling is shown.
 - Searches themselves never earn credit. Intentional note engagements—edit selection, manual expansion, full-screen view, shell/todo command execution—increment the note's raw explicit/inherited searchable tags once per active tab/search flow. Leaving for another tab or executed search and later returning starts a new flow, so a later shell run can count again. Successfully adding explicit tags separately credits only those newly added tags; removals and case-only changes are neutral. Accepting a search suggestion by mouse or keyboard credits that selected tag once, with no engagement-flow deduplication. Clicking a search-context tab credits each known positive tag term in its executed query once; excluded tags and quoted text are ignored. Programmatic tab restoration/switching, collapse, search execution, hover, render, and scroll are neutral.
+- After one or more completed tags, the remaining suggestions (only tags that still leave results) are ordered by how closely their notes overlap with the notes matching the tags already typed, so specific companions come before tags that are common everywhere.
 - Activity uses sparse per-calendar-day counts. A window sums the relevant daily buckets, selects its highest-count matching tag, and excludes tags chosen by earlier windows. No decay calculation or all-time score exists. The latest 365 populated days are retained, so unused calendar days consume no buckets.
 - In password-protected namespaces, all retained daily buckets live together in one authenticated encrypted payload. The database exposes only one random row UUID, ciphertext, nonce, and authentication tag—never dates, tag names, counts, queries, or changed-tag metadata.
 - A typed prefix can match either the start of the full tag or the start of any connector-separated segment.
@@ -158,6 +162,11 @@ Text matching is:
 - Case-insensitive (`casefold`).
 - Against **visible text**, extracted by stripping HTML (scripts/styles ignored).
 - Also against tag-bar `/* ... */` comment text (whitespace-normalized).
+- A space at the edge of the quotes marks a word boundary on that side: `"fat "` needs
+  the word to end there (a space, punctuation or the end of the text follows), so it
+  matches "fat cat" and "fat." but not "father"; `" fat"` needs it to start there, so
+  it does not match "sulfate"; `" fat "` matches only the word "fat". Without edge
+  spaces a term matches anywhere, also inside words (`"fat"` matches "father").
 
 ### UUID Terms
 - UUIDs in positive terms are treated as direct note targets (including when pasted as `[[UUID]]`).