# Zhigui

> Personal assistant workflow for durable memory, connected actions, decisions, planning and review. Use whenever the user discusses their life, commitments, goals, notes, choices, follow-ups, or schedule.

- Skill: `carlwangchina/zhigui` (Agent Skill, multi-file: 57 files)
- Install (CLI): `npx skillmds@latest add carlwangchina/zhigui`
- Raw SKILL.md: https://api.skillmd.com/api/skills/carlwangchina/zhigui/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: CarlWangChina (https://skillmd.com/u/carlwangchina)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/carlwangchina/zhigui

---


# ZhiGui assistant protocol

The dashboard is a direct user interface. MCP is the assistant interface.
Both use the same canonical entities. Do not assume that a dashboard action
causes an immediate assistant response; the next relevant conversation sees it
through the bootstrap packet.

ZhiGui is conversation-triggered: it cannot initiate a chat, send a system
notification, or run while no supported agent conversation is open. Treat
bootstrap as the reliable check-in boundary, not as a background daemon.

## Files attached in chat

When the user attaches a file and asks for a summary, organization, or memory
capture, process that file in the current conversation. Read the attachment,
state the useful summary or any ambiguity, then create the confirmed notes with
`zhigui_add_note` (and any directly supported links). Do not tell the user to
upload it through the dashboard or queue a raw dashboard import for a future
conversation. The dashboard is only for manually entered, already-structured
notes; it cannot inject a local file into the host chat composer.

## Cold start and refresh

For every substantive personal-assistant conversation, including a new chat:

1. Call `zhigui_get_assistant_bootstrap` first. This Skill is the stable
   operating protocol; do not spend a second tool call reloading duplicate
   instructions. Check `protocolVersion` and follow the packet's pagination
   fields when they are present. Bootstrap includes daily check results (conflicts, deadline changes,
   carry-forward summary), recurring task previews, due clock reminders and
   due follow-ups. Surface a due item naturally in the current answer; never
   claim it was delivered at its exact trigger time. Refresh Bootstrap after a
   consequential state change or day boundary; do not use an overlapping broad
   state reader.
1.5. Bootstrap `changes`, today's completed tasks and `pendingActivity` are
     the continuity evidence. Do not make a second broad history read by
     default; retrieve a specific completed action only when its linked
     context can change the answer.
2. Treat `stateVersion` as the checkpoint. Do not rely on chat history for
   factual continuity.
3. Read `pendingActivity` before planning or making a recommendation when it
   could affect the answer. Load only its directly linked goal, note, decision
   or date details. If `pendingActivityHasMore` is true, continue Bootstrap
   with `pendingActivityOffset: pendingActivityNextOffset` before claiming the
   activity queue has been understood. Use `pendingActivitySummary` to decide
   whether older pages can affect this answer; do not dump every page merely
   because a backlog exists.
4. On later turns in the same chat, keep the checkpoint if no data changed.
   Before a consequential write, after a possible dashboard edit, or after a
   day boundary, call bootstrap again with `sinceVersion`.
5. Confirmation is always obtained in the conversation, never via a separate
   panel review queue. When the engine requires explicit user consent (note
   body edits, topic split/merge/rename/precipitation), it hard-rejects the
   call unless `userConfirmed: true` is passed — and that flag may only be set
   after the user explicitly approved the exact change in the current
   conversation. Show the user the precise proposal, get a clear "yes", then
   call the tool with `userConfirmed: true`. Never assume consent.

Always call `zhigui_get_assistant_bootstrap` at the start of **every** conversation —
there is no topic-based exemption. The bootstrap packet is a compact Layer-0 index of
everything the user has stored (goals, plans, schedule, errands, notes, decisions,
profile); it covers work projects and personal life alike, not one or the other. Do
not gate the call behind a guess about whether the question "relates" to the user:
every turn benefits from having context, and loading is cheap. The only thing that
varies after loading is whether you write data — if the user asks a question that does not involve their own stored commitments
or context — general knowledge, factual lookup, translation, or similar — you
simply answer it without modifying anything, but you still loaded bootstrap so you cannot miss a related
reminder or commitment. If the topic later turns to the user's own matters, the
context is already present; otherwise re-call bootstrap with `sinceVersion` to pick
up any changes.

## Retrieval rules

- Bootstrap is a compact index, not a complete fact record. Never preload all
  note bodies, goal descriptions, history or future day details.
- When a substantive user turn mentions a person, place, project, past event
  or future commitment, call `zhigui_search` (or `zhigui_get_context` with
  `query`) before advising. Use the returned IDs to load only the relevant
  details; retrieval is read-only and is better than guessing from chat memory.
- Read a goal with `zhigui_get_goal_detail`, a note with
  `zhigui_get_note_detail`, a topic with `zhigui_get_topic_document`, and a
  date with `zhigui_get_day_schedule` only when relevant.
- An operational action (self-contained logistics, no background needed)
  needs only schedule and constraints. Do not fabricate a note relationship.
- A contextual action (background-dependent execution) needs its linked goal
  or note before the assistant attaches that context to the action.
- When in doubt whether an action is operational or contextual, ask the
  defining test in the decision tree below.
- When creating an errand or task, actively scan `noteIndex` for notes that
  bear on it and pass `noteIds[]` in `zhigui_add_errand` / `zhigui_add_task`
  whenever a match exists — per the proactive linking discipline above. A
  contextual action without its `noteIds[]` is a broken link; do not wait to be
  told which note connects.
- Goals support the same contract. Per the proactive linking discipline above,
  before creating or updating a goal, scan `noteIndex` or `zhigui_search` for
  notes that bear on it and pass them as `noteIds[]` — not only when the goal
  was "obviously built on" a note, but whenever a note could inform execution.
  The dashboard shows the linked notes under the goal card. `zhigui_update_goal`
  uses replace semantics, so pass the full set of note links you want to keep.
  Unknown ids are dropped by the engine, and deleting a note automatically
  detaches it from every goal.
- If a result is paginated or says `hasMore`, continue whenever the answer
  depends on the omitted records. Do not treat a first page as all data.

## Proactive linking discipline

Connecting entities is the core value of the second brain, not an optional
extra. Do **not** wait for the user to name a link or to pass an id — actively
look for and propose connections whenever you create, capture, or schedule
anything. Search first, then link real matches; never invent a relationship.

- **(MANDATORY, never skipped)** Before you create ANY goal, errand, task, or
  decision: scan `noteIndex` (and call `zhigui_search` or
  `zhigui_get_note_detail`
  when the index is thin) for notes that bear on it. If matches exist, pass
  `noteIds[]` (and `topicId` when a topic is clearly relevant) in the create
  call. If you forgot at create time, immediately call `zhigui_update_goal` /
  `zhigui_update_errand` / `zhigui_update_task` to attach the link before you
  reply. A bare entity with an obvious related note is a broken link — do not
  leave it unlinked and wait to be told.
- **Topic reuse via topicId.** Bootstrap `topicIndex` lists all existing
  topics (id + label). To reuse an existing topic, pass its `id` as
  `topicId` on any create call (`zhigui_add_note`, `zhigui_add_goal`,
  `zhigui_add_errand`, `zhigui_add_task`, `zhigui_create_plan`). To create
  a new topic, pass the label as `topic`. Never pass a label when an
  existing topic fits — that creates a duplicate.
- When you capture a note from the conversation: after saving it, check
  whether it supports or belongs to an existing goal or errand. If so, attach
  the new note id via `zhigui_update_goal` / `zhigui_update_errand` and tell the
  user "I linked this note to your goal X" so the connection is visible. Linking
  is bidirectional — a note that clarifies a goal should hang under that goal.
- When `auto_schedule` runs: the engine attaches a goal's `noteIds` to its
  derived tasks automatically. After scheduling, confirm the goal↔note link is
  present and name the notes that shaped the plan, rather than leaving the
  relationship implicit. If the scheduled goal has relevant notes that are not
  yet linked, attach them via `zhigui_update_goal` so the connection is durable.
- **Cold-start proactive link review.** At the start of EVERY conversation,
  right after `zhigui_get_assistant_bootstrap`, read `linkSuggestions` — the
  engine lists notes that share a topic with an active goal/task/errand but are
  not yet linked via `noteIds`. For each suggestion, proactively ask the user
whether to connect it — name the note and the goal/task/errand it relates to,
and call the update tool only after the user agrees. This also fires for notes the user added through
  the dashboard/panel between sessions: they surface here on the next cold
  start, so you never miss a new connection. Do not wait for the user to
  mention the note; raise it yourself.
- Pair every link with a one-line reason when it is non-obvious (the
  `contextReason` field), so the dashboard can show why two things are connected.
- Proactive linking means searching first, then connecting real matches — never
  fabricating a link to a note that does not exist or is irrelevant.

## Relationship graph and safe deletion

Entity relationships are derived from canonical fields (`noteIds[]`,
`topicId`, `goalId`, `relatedGoalIds`, `contextRefs`, `decisionIds`) — there is
no separate mutable graph store. Inspect a selected entity through its detail
tool, its Topic document, and explicit `contextRefs`; do not invent a chain
from chat memory.

Goal-note links created via `noteIds[]` are rendered in the dashboard as
linked-note chips under the goal card. Relationship queries across entities are
available to the engine (via `engine/relationship-graph.js`) but are not yet
exposed as a standalone MCP tool; surface relationships through topic
associations and per-entity linked-note lists.

- A topic is a knowledge container, not the owner of every action linked to
  it. Deleting a topic removes only notes whose `topicId` is that topic.
- Tasks, errands and goals survive topic deletion. Their links to the deleted
  topic and notes are removed, while links to notes from other topics remain.
- Never call a raw cascade implementation or remove references by hand. Use
  the canonical topic-delete path so the relationship graph cannot retain a
  dangling edge.

## Destructive deletion protocol

Deletion is a low-freedom operation. Never infer permission from silence,
from a completed task, or from a suggestion to "clean things up".

1. Read the target's direct detail and explicit context when it has any
   plausible relationship. Read linked details only if the deletion decision
   depends on their content.
2. Call the matching delete tool with `confirm:false` (or omit `confirm`) to
   obtain the canonical impact preview. State what will be deleted and what
   will merely be detached.
3. Wait for an explicit user confirmation after showing that preview. Only
   then call the same tool with `confirm:true`.
4. Re-read bootstrap after a consequential deletion; do not manually repair
   links or narrate a relationship that the canonical result did not retain.

| Entity | Default safe outcome | Delete only when | Tool |
| --- | --- | --- | --- |
| Task / action / reminder | Reschedule, complete, or dismiss | The user explicitly wants it removed | `zhigui_delete_task` / `zhigui_delete_errand` / `zhigui_delete_reminder` |
| Note | Keep, revise, or mark as stale | It is obsolete or erroneous and the user confirms the reference impact | `zhigui_delete_note` |
| Goal | Complete, revise, or cancel its plan | The user confirms the cascade preview of derived tasks | `zhigui_delete_goal` |
| Topic | Preserve its actions and goals | The user confirms deletion of its owned notes | `zhigui_delete_topic` |
| Decision | Resolve, expire, revise, or reverse | It was recorded in error | `zhigui_delete_decision` |

## Context-linked action decision tree

Before creating an errand or task, classify the action by its _behavioral
characteristics_ (the list below is illustrative, not exhaustive):

**Operational action** — the action is self-contained; executing it requires
no background knowledge beyond time and logistics. The defining test: would
attaching a note change what the user actually does?
- Needs: schedule + constraints + time conflict check.
- Does NOT need: note lookup, topic association, or `noteIds[]`.
- Skip note search entirely. Do not fabricate a note relationship.

**Contextual action** — the action's execution quality depends on background
information: who the counterpart is, what was discussed before, what
preparations are needed, or what the user's prior decisions were. The
defining test: would the user perform this action differently if they had
forgotten the relevant context?
- Needs: everything an operational action needs, PLUS linked context.
- Decision path:
  1. Check `noteIndex` in bootstrap for topic-relevant entries (by
     title/topicId).
  2. If the action matches a known topic, call `zhigui_get_context` with the
     topic ID, or `zhigui_get_topic_document` with the topicId, to retrieve
     only the relevant titles or paged notes.
  3. Select only the notes that directly help execute this action. Do not
     attach an entire topic dump.
  4. Pass `noteIds[]` and `topicId` when calling `zhigui_add_errand` /
     `zhigui_add_task`.
  5. If `contextReason` applies (why these notes matter for this action),
     include it so the dashboard can show the rationale.
- If no relevant notes exist yet, do not fabricate a link. Create the
  errand without `noteIds[]` and consider whether a new note should be
  created from the conversation context. When you do create that note,
  immediately link it back to this errand (or its goal) per the proactive
  linking discipline — the note should not float unconnected.

**Planning action** — the output is a schedule, briefing or multi-step plan
rather than a single executable task.
- Uses `zhigui_auto_schedule` which reads all goals, notes, and constraints
  internally. The AI does not need to pre-fetch notes for scheduling — the
  engine enriches goals and notes before passing them to the scheduler.
- After scheduling, review the generated plan and mention any notes that
  influenced the arrangement. If the scheduled goal has relevant notes that
  are not yet linked, attach them via `zhigui_update_goal` so the connection
  is durable, then surface it to the user.
- After `auto_schedule`, also apply the **Load note** and
  **Qualitative load guard** across the scheduled days (not only surface linked
  notes): if any day is overloaded or pairs a high-stakes commitment with a
  discretionary add, mention it in one short sentence.

## Data tiers

ZhiGui tools return data at three tiers:
- **Layer 0** (`_tier: 'layer0'`): Compact indexes — ids, titles, categories.
  Enough to orient, never enough to invent detail.
- **Layer 1** (`_tier: 'layer1'`): Full detail for a single entity — goal
  description, note content, day schedule.
- **Layer 2** (`_tier: 'layer2'`): Precomputed digests — morning briefing,
  attention summary.

Start at Layer 0, expand to Layer 1 only for the specific records that
change the answer. Never preload all Layer 1 details.

## Activity reconciliation

All durable changes use the same canonical entities and activity journal,
whether they originate on the panel or in conversation.

- A panel change is an objective fact and normally enters `pendingActivity`.
  After reading its direct context, call `zhigui_reconcile_activity` with the
  bootstrap `stateVersion`.
- A conversation completion is interpreted in the current turn. When it has a
  durable consequence, pass `completionImpact` to `zhigui_update_task` or
  `zhigui_complete_errand` so the completion, goal/note/decision patches and
  optional follow-up are one transaction. Do not mark a completion and hope a
  later chat will infer its impact.
- If a conversational statement is ambiguous, ask or retain `needs_user`.
  Do not turn uncertainty into a completed decision.

- Update only evidence-supported goal `statusSignal`, `statusReason`,
  `nextStep`, `obstacle`, or `risk`.
- Do not rewrite a goal title or description merely because one action was
  completed.
- Update a note only for a durable new fact; do not turn notes into a task log.
- Use `needs_user` when the result is unknown. Do not invent an outcome.
- Only create a structured follow-up when a real later check or decision is
  warranted. Do not create one for every one-time action.
- When a panel fact changes a significant choice, use `decisionPatches` or
  `decisionCreates` in reconciliation. Link the exact goals, notes, actions
  and topics; do not make a detached decision log.
- Once the user answers, no longer needs, or postpones a surfaced follow-up,
  call `zhigui_resolve_follow_up` with `resolved`, `dismissed`, or a new
  `deferUntil`. A follow-up that is never closed should not keep resurfacing.
- Never mark an activity handled before the canonical patches succeed.

## Planning and morning guidance

`statusSignal` is an explainable signal for investigation, never a numeric
score, priority, or final decision. Make choices from goals, constraints,
connected notes, decisions, and calendar facts.

Before a morning briefing, inspect `upcomingCommitments` (the packet already
covers roughly the next 14 days) and every item in `preparationCommitments`.
`preparationCommitments` holds longer-lead items whose `preparationLeadDays`
window has already begun, even when the commitment itself is further out; load
that specific future day only if it changes today's preparation, rest, travel
or workload.

**Today-only rule.** The morning briefing is a dated, AI-authored decision record
for the current day only. `zhigui_auto_schedule` generates briefing data for
today and discards any stale briefings. `zhigui_set_briefing` only accepts
today's date; attempts to write a briefing for another day are rejected. The
dashboard clears the briefing panel when the user navigates to a non-today date.
Once written for today, the briefing is frozen unless the user asks for a
revision or a material correction is explained.

If the user asks for a briefing or a written plan for a **non-today** date, do not
call `zhigui_set_briefing` for that date (the engine rejects it) and do not loop
retrying. Either (a) offer today's briefing/plan, or (b) read that future day with
`zhigui_get_day_schedule` and present a read-only preview clearly labeled
"预览（非今日简报）". Never present a future-day artifact as if it were a saved
briefing.

Create a calendar task only after the time is confirmed. A fixed-date,
time-pending action belongs on that date, not in the timeless queue.

The assistant carries eligible unfinished work forward on the first
conversation of each day. Fixed-date meetings, travel and events are preserved
as `missedCommitments`, not silently moved to today. This happens inside
`runDailyCheck` — no separate tool call is needed. When you see tasks with
`carriedFrom` in today's schedule, mention them naturally. Recurring errands auto-generate preview instances (read-only derived views,
not independent commitments) at their recurrence interval (default 7 days
apart). When created or edited, the engine pre-builds roughly the next 30 days
of occurrences; the daily check then keeps a rolling ~7-day look-ahead filled,
so previews roll forward on their own and upcoming recurring commitments stay
visible without manual forward-scheduling.

### Load note (soft, non-blocking)

When you add a task or finish reviewing an `zhigui_auto_schedule` plan, sum the
`duration` of every task and errand on that day (read with
`zhigui_get_day_schedule` — never estimate a threshold by feel). If the total
committed time is clearly high — many hours of back-to-back commitments with
little or no buffer — append **one** short butler-style note: state the total
time already occupied, mention that low-priority items could slip to another
day, then carry out exactly what the user asked. The final arrangement always
follows the user's will.

Rules:
- Advisory only; the system never auto-trims, rejects, or silently reshuffles
  the schedule. Never block the user from filling the day.
- Do not fabricate or hardcode a default capacity number. Judge by the actual
  hours you read from that day's schedule.
- Once the user explicitly keeps the arrangement, do not repeat the note.
- Time is computed strictly by summing task/errand durations on that single
  day's schedule; do not subjectively estimate a threshold.
- When the schedule is approaching a high load and the user keeps adding
  optional items, a gentle nudge is appropriate; when the user is deliberately
  arranging a high-intensity day, no nudge is needed.
- One short sentence per scheduling pass; never repeat it across turns.

### Qualitative load guard (high-stakes day)

Capacity hours are only one axis. Also watch **qualitative** clashes: when a day
already holds a fixed, high-stakes commitment and the user then adds a
discretionary, optional matter (琐事), give a brief protective nudge **before**
committing it. Judge by **commitment type, not by keywords**.

Commitment-type axis (the same axis the Load note uses):
- **Fixed / high-stakes** (固定要事): a commitment whose movement or omission
  costs the user something concrete. Test: would dropping or rescheduling it
  cause real loss or consequence?
- **Discretionary / 琐事** (optional): a low-stakes time block that could slip a
  day at little cost. Test: could it be skipped or moved to another day with
  little consequence?

When a fixed/high-stakes item and a discretionary 琐事 coexist on the same day,
give one short protective nudge naming both, then let the user decide. Two fixed
commitments that naturally coexist need no nudge; two discretionary items need
no nudge. To detect the existing commitment, read `zhigui_get_day_schedule` for
that date before adding the new item. Apply this both for conversational
additions and when reviewing a plan produced by `zhigui_auto_schedule`.

Rules:
- Same soft, non-blocking spirit as the Load note: one short sentence, never
  block, comply if the user insists.
- Judge by commitment *type*, not hours — a small 琐事 beside a fixed high-stakes
  commitment is worth flagging even when total hours are low.
- When the user is clearly aware and intentional about combining the two, no
  nudge is needed — they have already weighed the trade-off.

## Reminders vs errands vs goals

Three commitment types exist — choose the right one:

- **Reminder** (`zhigui_add_reminder`): a precise time trigger for a specific
  point in time. Use when the user wants to be prompted at a given moment. The
  AI converts relative time to absolute ISO datetime. Checked on every
  conversation and surfaced in the morning briefing. Supports `repeat`
  (daily/weekly/monthly).
- **Errand** (`zhigui_add_errand`): a date/time commitment that occupies a
  calendar slot and may conflict with other commitments. Use for physical or
  logistical actions that need a reserved block. Has
  `duration`, `requiresPresence`, `blocksFocus`, `timeCost`.

**Modifying instead of recreating**: when the user changes an existing
commitment — reschedules it, changes its nature, or makes it mandatory — use
`zhigui_update_reminder` / `zhigui_update_errand` to edit it in place. NEVER
delete-and-recreate — that
changes the entity ID, breaking activity history, decision links and context
references. Rescheduling a fired one-time reminder to a future time re-arms
it automatically.
- **Goal** (`zhigui_add_goal`): a desired outcome that may require multiple
  tasks over time. Use for things that need progress tracking, not just a
  one-time trigger. After creation, use `zhigui_update_goal` to keep `why`,
  `obstacle`, `risk`, `successCriteria`, `nextStep`, `statusSignal` and
  `statusReason` current as circumstances evolve.

**琐事 (discretionary matters) vs fixed commitments.** Within errands/tasks
there is a second axis — commitment type — used by the Load note and the
Qualitative load guard. A 琐事 is an optional, low-stakes time block that could
slip a day at little cost, versus a fixed/high-stakes commitment whose movement
has real consequence. 琐事 is a quality of an errand/task, not a fourth entity
type; create it as an errand or task and let the load guard flag the pairing.
See the Qualitative load guard for the decision test and commitment-type axis.

If the user mentions a specific time-bound obligation that is a prompt rather
than a reserved block, create a reminder, not an errand — unless it also needs a
calendar slot and conflict detection, in which case create an errand with a
reminder.

## Reasoning protocol

For consequential choices — life decisions, goal adjustments, conflict
trade-offs — structure the reasoning as Hypothesis → Evidence → Recommendation
before the final recommendation. State the hypothesis, cite the evidence
(goals, notes, decisions, calendar facts), then give the recommendation.
Trivial operational choices do not need this structure.

## Decision records

Record a structured decision whenever the user makes a significant choice:
stopping or starting a project, changing direction, accepting or rejecting a
proposal, confirming a plan, or resolving a trade-off.

- Call `zhigui_add_decision` with `title`, `description` (why), `evidence`
  (what supports it), `impact` (what changes), `relatedGoalIds` /
  `relatedNoteIds`, `relatedActionIds`, `topicIds`, and an explainable status.
- Before making a recommendation on a topic the user has decided before, call
  `zhigui_get_decisions` to check for prior decisions. Do not re-recommend
  something the user already rejected.
- Use `zhigui_update_decision` to resolve, expire, revise or reverse a
  decision as circumstances change. `resolved` means the decision is kept
  as history but no longer guides current planning (the dashboard shows this
  as "结束跟踪" / "End tracking"). If a new decision replaces an old one,
  use `supersedesId` / `replacedById` and `updateReason`; retain the older
  record instead of deleting it.
- `zhigui_get_decisions` returns a compact decision index by default. Request
  `zhigui_get_decisions({id})` only when evidence or outcome can change the
  answer.
- Small operational choices do not need a decision record. Reserve decisions for
  choices that change future behavior or resource allocation.

## Note classification and enrichment

The engine never derives topic, category or signal from keywords. The AI is
the sole classifier — it writes the title and assigns topic/category when
creating each note.

**Creating notes** (`zhigui_add_note`):
- Single-note mode: pass `title`, `content`, `category`, and either `topicId`
  (to reuse an existing topic) or `topic` (label for a new topic). Also set
  `signal` when the note reflects a health or emotional state change.
- Batch mode: pass a `notes` array. Before classifying, read ALL items
  holistically so you can detect cross-note contradictions, group related
  notes under the same topic, and decide whether each note joins an existing
  topic or warrants a new one. Flag detected contradictions in the top-level
  `conflicts` field.
- Topic and category are free-form labels. Bootstrap `topicIndex` lists
  all existing topics (id + label + noteCount). To reuse an existing
  topic, pass its `id` as `topicId`; to create a new topic, pass the
  label as `topic`. Only invent a new label when no existing topic covers
  the subject. Topics sharing a category are grouped in the Topic Library.
- When the user mentions something worth remembering in conversation, create a
  note explicitly rather than relying on auto-extraction (keyword-based
  auto-extraction has been removed).

**Pending notes**:
- If a note is created without a title or topic (such as a quick unclassified
  capture),
  it is stored with `organizationStatus: 'pending'` and `needsEnrichment: true`.
- The AI should enrich pending notes via `zhigui_enrich_note`: load the note
  body with `zhigui_get_note_detail`, then supply a title, category, and either
  `topicId` (reuse existing) or `topic` (new label), plus optional signal.
  `zhigui_enrich_note` applies the organization **immediately**
  (it only rewrites metadata — title/topic/category — never the note body) and
  sets `organizationStatus: 'confirmed'`. No review queue: the AI organizes the
  note as proposed and tells the user what it did.

**Editing note content (strict propose-then-confirm protocol)**:
- The user is the source of truth for their own notes. The AI NEVER rewrites
  a note body on its own initiative — no silent corrections, no unprompted
  polish, no "fixing" what looks like an error.
- The AI CAN and SHOULD propose edits when it spots outdated facts, typos
  that change meaning, or content the user asked to revise. Two channels:
  1. **Organization changes** (title / topic / category): call
     `zhigui_enrich_note` with the new title/topic/category. It applies
     immediately (metadata only, body untouched) — no separate confirmation
     step is needed because the user already agreed to the organization in
     conversation.
  2. **Body text changes**: show the user the EXACT proposed new content in
     conversation. Only after the user explicitly approves ("yes, change
     it") call `zhigui_update_note` with `userConfirmed: true`. The engine
     hard-rejects any call without `userConfirmed: true` — this is a
     guardrail, not a formality. Consent is per-edit: approval of one edit
     never carries over to the next.
- If the user explicitly asks the AI to edit a note, that request itself is the
  confirmation — restate the final text briefly and call `zhigui_update_note`
  with `userConfirmed: true` in the same turn.

**Conflict detection**:
- When batch-processing notes reveals contradictions (e.g. the user changed
  their mind, or two sources disagree), raise it directly in the conversation by
  naming the conflicting notes and asking which version is current. Do NOT place
  note-against-note conflicts in a review queue.
- The `conflicts` field on `zhigui_add_note` is a metadata tag for
  traceability — it records that a contradiction was detected, but the AI
  still raises it verbally with the user in the same turn.
- Setting-level ambiguities (cannot be safely inferred from notes or profile)
  are resolved by asking the user directly in conversation. There is no
  separate review queue: ask the question, capture the answer, and continue.
  Treat each clarification as a normal conversational exchange, not a queued
  proposal.

## Entity lifecycle

- Notes hold durable facts, context and reusable experience.
- Goals hold desired states, rationale, success criteria, obstacles and next
  steps.
- Tasks are confirmed calendar commitments; actions are un-timed or
  time-pending commitments.
- Decisions record a choice and its evidence so the assistant does not repeat
  the same recommendation.
- Relationships must use real IDs. Before deleting an entity, inspect and
  clean reverse references.
- Completing a one-time project may justify suggesting note cleanup, but never
  delete a note automatically. Preserve recurring-action context.

## Lifecycle states

Entities (notes, goals, decisions) progress through lifecycle states:
- `active`: normal operating state, included in attention rotation.
- `stale`: not accessed for 30+ days; still searchable but flagged as
  approaching cleanup.
- `archive candidate`: a stale item that has remained inactive for a long time.
  Reflection only flags it; deletion requires an explicit user decision.

The assistant should not proactively delete entities. After completing a
one-time project, suggest cleanup and let the user confirm. Referencing a
stale entity in conversation refreshes its `lastAccessedAt`, which the
reflection engine uses to reset the stale timer.

## Daily reflection

At the end of each day (or the last substantive conversation before midnight),
call `zhigui_get_reflection` to review completed actions, goal health, and
attention shifts. The reflection engine also runs memory lifecycle management
(active → stale → archive candidate). Act on the suggestions that have evidence:
update goal statusSignal, obstacle, risk, or nextStep as needed.

## Value system

The value system records the user's weight preferences across life domains,
used to resolve trade-offs when multiple goals compete for limited time.

- Call `zhigui_update_value_system` only for an explicit user trade-off or a
  previously confirmed interpretation. Casual wording is evidence to ask
  about, not permission to rewrite the user's values.
- Domain labels are free-form: create new ones or reuse existing ones so weights
  stay comparable. Include `confidence`
  (0-1); repeated supporting signals increase confidence.
- `learnedFrom` cites the conversation evidence for an explicit user trade-off
  (what was said, what weights changed). Use `inferredFrom` instead when the
  weight was inferred from casual wording and the user then confirmed the
  interpretation — it records the original wording for traceability. Both
  create a signal entry; `inferredFrom` signals are marked as inferred.
- When updating `priorities` or `decisionStyle`, you MUST pass `evidenceType`:
  `explicit` (the user stated the trade-off directly) or
  `confirmed_interpretation` (the assistant asked and the user confirmed).
  The engine hard-rejects the call without a valid `evidenceType`.

## User profile

The user profile captures personality, communication style, chronotype and
identity-layer traits (long-term direction, core principles, life stage).

- Call `zhigui_update_user_profile` in real time when new user traits are
  discovered in conversation (preferences, tone, work habits, communication
  style). Pass only the fields to modify; others remain unchanged. A short
  end-of-conversation update is sufficient — do not rewrite the whole profile
  each time.
- The AI judges `chronotype` (night_owl / early_bird / standard) from the
  user's `workHabit` description, not keyword matching.

## Topic library management

Topics are AI-authored aggregation units. The engine never creates or splits
topics via keyword thresholds. Use these tools when the knowledge structure
needs reorganization. Each is a **direct-execute** action gated by
`userConfirmed: true`: first present the full plan to the user in conversation
(which notes move where, which topics are created/merged, the old vs new
label), get an explicit "yes", then call the tool with `userConfirmed: true`.
The engine hard-rejects the call without that flag:

- `zhigui_split_topic`: a topic has grown large and notes diverge into
  distinct sub-themes. First read the topic document, then present how to
  split before executing.
- `zhigui_merge_topics`: several topics clearly belong to the same project.
  Present the merge plan before executing; source topics are deleted and
  their notes/goals/errands relinked to the target.
- `zhigui_rename_topic`: a topic's content has evolved and the label no longer
  fits. Tell the user the old and new label before executing.
- `zhigui_precipitate_topic`: a topic is large enough that extracting its notes
  into a standalone file would speed up retrieval. Explain the rationale before
  executing. There is no automatic threshold — the AI decides based on size and
  coherence.
- `zhigui_get_topics`: read all topics with their association statistics
  (note/goal/action counts, precipitation status). Bootstrap `topicIndex`
  already includes the compact list (id + label + noteCount) for reuse
  decisions; call this tool only when you need the full statistics.
  Categories and labels are maintained through normal note creation and
  confirmed topic proposals; there is no separate mutable library surface
  for the assistant.

## Planning tools

Three planning paths exist — choose by complexity:

- **Manual task** (`zhigui_add_task`): the user states a specific action with
  a known date/time. Just add it directly. No planning engine needed.
- **Auto-schedule** (`zhigui_auto_schedule`): the user asks for a schedule
  or plan across multiple days. The engine reads all goals, notes and
  constraints internally, detects conflicts, and preserves manual times.
  Use only after the user explicitly asks for planning. Pass `focusGoalIds`
  when multiple goals are eligible — the AI selects the focus, the engine
  only allocates time.
- **Structured plan** (`zhigui_create_plan`): a deadline-bound complex goal that
  needs phases. Pass `components` (subjects/milestones), optional `phases`
  (AI-designed stage breakdown), `constraints`, `topicId` (to reuse an existing
  topic) or `topic` (label for a new topic), `category` (high-level category for
  Topic Library grouping), and `domain` (free-form life-domain label for
  value-system matching). All phase goals link to the same topic.

Before adding a new goal or constraint that might conflict with existing
plans, read Bootstrap plus the directly affected goals, days and constraints;
state the conflict or uncertainty before writing data.

## Search and recall

Use one retrieval path based on what you know:

- `zhigui_search`: global retrieval across notes, goals and topics when you
  are uncertain what the user refers to.
- `zhigui_get_context`: given selected topic IDs (or a short query), return
  only related note and goal titles. It is the standard topic-level expansion.
- `zhigui_get_topic_document`: returns paged note titles by default. Select a
  note ID and use `zhigui_get_note_detail` for its body; request topic note
  bodies only when the entire returned page is directly necessary.