tips working and optimized

docs/HELP_GUIDE.md

@@ -2,7 +2,7 @@
 
 This document is a thorough reference for how TasGrid works today. It is intended to support future help tooling, deeper troubleshooting, and advanced feature explanations. It is not meant to match the shorter in-app Help screen one-to-one.
 
-## Purpose and Scope
+## Overview
 
 - This guide focuses on end-user and team-lead features inside TasGrid.
 - It explains both normal workflows and important behavior that may confuse users if it is not documented.
@@ -20,6 +20,9 @@ This document is a thorough reference for how TasGrid works today. It is intende
   - `@bucket` for a shared bucket context
   - `#note` for note-linked workspaces
 - These special tags are not just labels. TasGrid converts them into structured relationships that affect visibility, ownership, and workflow behavior.
+- For tasks, the important persisted relationship fields are `labelTags`, `shareRefs`, and `noteRefs`.
+- The user-facing tag list is effectively a derived view built back from those structured relationships, plus the user's hidden favorite tag when applicable.
+- This means editing tags is not a purely decorative string change. TasGrid reinterprets the tag list and normalizes it back into structured refs.
 
 ## Navigation and Access
 
@@ -40,21 +43,33 @@ This document is a thorough reference for how TasGrid works today. It is intende
   - `Snowball`
   - `Dig In`
   - `Progress`
-- The bottom of the sidebar includes `Help`, `Settings`, and the context switcher.
+- The context switcher sits near the top of the sidebar above the task views.
+- The lower utility area includes:
+  - `Ask Questions`
+  - `Help`
+  - `Settings`
 - The sidebar supports locked, collapsed, and peek states.
 
 ### Mobile Navigation
 
 - The mobile bottom nav exposes:
   - `Focus`
-  - `Matrix`
   - grouped `Value` views for `Priority` and `Urgency`
+  - `Matrix` inside the `Value` group
   - grouped `Flow` views for `Snowball`, `Dig In`, and `Progress`
+  - `Ask`
   - `Settings`
 - Mobile does not have a dedicated Help tab in bottom navigation.
 - Help is reached through `Settings > Resources > Help`.
 - The mobile context switcher is a floating control near the top-left area of the screen.
 
+### Ask Questions Access
+
+- `Ask Questions` is a built-in question panel for looking up how TasGrid works.
+- On desktop it opens inline inside the sidebar so it can be used alongside the rest of the app.
+- On mobile it is a dedicated bottom-nav destination labeled `Ask`.
+- The current implementation is guide-grounded rather than general-purpose: answers are intended to come from the TasGrid reference material rather than from outside product knowledge.
+
 ### Help Access
 
 - Desktop Help is available from the left sidebar.
@@ -62,7 +77,7 @@ This document is a thorough reference for how TasGrid works today. It is intende
 - Some higher-confusion areas include direct Help links that open the relevant help section.
 - Help supports deep-link anchors in the form `#help/<section-id>`.
 
-## Tasks
+## Task Creation and Editing
 
 ### Task Creation
 
@@ -116,6 +131,7 @@ This document is a thorough reference for how TasGrid works today. It is intende
   - rich description/content
 - Task detail auto-saves changes.
 - Some saves are debounced rather than written instantly.
+- Tag edits are interpreted into `labelTags`, `shareRefs`, and `noteRefs`, then written back as a normalized task state.
 - If a user inserts an `@person` mention into task content, TasGrid also adds that matching `@person` context tag so the task participates in sharing correctly.
 
 ### Task Card Actions
@@ -131,6 +147,8 @@ This document is a thorough reference for how TasGrid works today. It is intende
 - Some collaboratively shared tasks show update indicators.
 - There is also a `Collapse until updated` behavior for reducing clutter on ongoing shared work.
 
+## Task Lifecycle and Scheduling
+
 ### Task Status and Progress
 
 - Task status is numeric from `0` to `10`.
@@ -307,7 +325,7 @@ These behaviors are important because a user may feel a task has disappeared whe
 - This is especially relevant for search and filters because a task cannot be found if it has not been loaded into memory yet.
 - Users may interpret missing search results as deletion when the actual issue is partial history loading.
 
-## Contexts, Sharing, Buckets, and Supervision
+## Contexts and Sharing
 
 ### Context Types
 
@@ -331,9 +349,11 @@ These behaviors are important because a user may feel a task has disappeared whe
   - `My Bucket`
   - pinned shared buckets
   - supervised personal contexts shared with the current user
-- Desktop places this at the bottom of the sidebar.
+- Desktop places this near the top of the sidebar above the task views.
 - Mobile shows it through the floating control.
 
+## Buckets and Supervision
+
 ### Shared Buckets
 
 - Shared buckets are team contexts created in Settings.
@@ -365,8 +385,22 @@ These behaviors are important because a user may feel a task has disappeared whe
   - an `@bucket` tag
   - a `#note` tag
 - This is the primary sharing model.
+- TasGrid parses those tags into structured `shareRefs` and `noteRefs` rather than relying on the display strings alone.
 - Documentation should not describe a separate manual share dialog as the main expected workflow.
 
+### `#note` Sharing Semantics
+
+- Applying a `#note` tag does more than add a label:
+  - it creates a `noteRef`
+  - it also creates a note-kind `shareRef`
+- A `#note` tag links the task into that note workspace. It does **not** mean "all teammates can now see this task."
+- Visibility from `#note` linkage is governed by note accessibility:
+  - if the note is private, only the note owner can gain visibility from that note link alone
+  - if the note is public, other authenticated users can gain visibility from the note link because the note is accessible to them
+- For explicit person-to-person or team sharing, use `@person` and `@bucket`.
+- If the goal is "make sure another specific teammate can see this task," `#note` alone is not the clearest or safest mechanism unless that teammate already has access to the note.
+- In implementation terms, note-linked visibility is checked through accessible `noteRefs`, while user and bucket sharing are checked through personal-context and bucket-context rules.
+
 ### Collaborative vs Handoff
 
 - TasGrid uses two important context policies:
@@ -391,6 +425,7 @@ These behaviors are important because a user may feel a task has disappeared whe
 - Some system-backed context tags are intentionally hidden in normal UI.
 - Hidden does not mean inactive.
 - A task may still belong to a person, bucket, or note even when the user does not obviously see the matching context tag in normal task chips.
+- In particular, the current user's own personal-context tag can be suppressed from visible task chips even though the underlying ref is still active.
 - This is one of the biggest sources of user confusion and should be treated as normal behavior rather than as data loss.
 
 ### Context Effects on Task Creation and Visibility
@@ -404,7 +439,7 @@ These behaviors are important because a user may feel a task has disappeared whe
   - trash
   - whether the task belongs to an unpinned bucket
 
-## Notes
+## Notes Basics
 
 ### Notes Mode
 
@@ -466,6 +501,8 @@ These behaviors are important because a user may feel a task has disappeared whe
   - matching `noteRefs`
   - matching note-based `shareRefs`
 
+## Note Sharing and Linked Work
+
 ### Public, Private, and Share Links
 
 - Notes can be public or private.
@@ -478,6 +515,8 @@ These behaviors are important because a user may feel a task has disappeared whe
 - If a note is private when the share link is copied, TasGrid prompts the owner to make it public first.
 - Public notes can be viewed through the embed route without normal auth when the note ID is present.
 - Public notes are editable in-app by non-owners, but owner-only controls remain restricted.
+- A public note can also make note-linked tasks visible inside the authenticated app because those tasks pass the note-access visibility check.
+- A public embed link should be treated as note-content access, not as a guaranteed full unauthenticated task workspace. Linked-task loading still depends on the in-app task-loading path.
 
 ### Child Tabs
 
@@ -508,6 +547,7 @@ Important privacy caveat:
 - A task counts as linked if either is true:
   - it has a matching `noteRef`
   - it has the matching `#note` tag
+- In practice, TasGrid treats the root note as the linking owner for that workspace, even when the user is currently inside a child tab.
 - Linked tasks are shown with incomplete items first, then ranked by combined score.
 
 Linked task actions include:
@@ -537,7 +577,7 @@ Current behavior caveats:
 - TasGrid also renames the corresponding `#note` tag definition after the note rename.
 - This helps linked tasks continue to point to the correct note workspace after the name changes.
 
-## Rich Editor
+## Rich Editor Basics
 
 ### Shared Editor Model
 
@@ -618,6 +658,8 @@ Current caveat:
 - in task detail, `Open Note` is wired to actual note navigation
 - in the notes editor, the preview appears but `Open Note` is not fully wired through the Notes view
 
+## Rich Editor Uploads and Embeds
+
 ### Uploads and Embedded Media
 
 - Upload flows are available through:
@@ -806,9 +848,11 @@ Background update behavior:
 - Like many PWAs, TasGrid can continue showing older cached assets until a service worker update is applied.
 - `Update App` and `Reset PWA` exist to help recover from stale-client issues.
 
-## Important Constraints and User-Facing Caveats
+## Common Confusions and Caveats
 
 - Sharing is primarily tag-driven, not driven by a separate share dialog.
+- `Ask Questions` is help-oriented and guide-grounded; it should not be treated as an authoritative source for behaviors that are not documented here.
+- Sharing a task to `#note` does not automatically mean every teammate can see it. It means the task is linked to that note workspace, and visibility then depends on whether the note itself is accessible.
 - Context tags may be hidden while still actively controlling task behavior.
 - Creating work in the wrong active context can place it somewhere unexpected.
 - Focus and Priority are not substantially different in current sorting behavior.
@@ -826,7 +870,9 @@ Background update behavior:
 - Bucket archive exists, but a confirmed user-facing bucket restore flow was not identified.
 - In the notes editor, note mention previews exist, but `Open Note` from that preview is not fully wired through the same way it is in task detail.
 
-## Explicit Exclusions
+## Reference Notes
+
+### Explicit Exclusions
 
 - SDK and API documentation
 - integration-developer workflows
@@ -835,6 +881,16 @@ Background update behavior:
 - admin-only repair or maintenance flows
 - inactive legacy settings UI hidden behind disabled conditions
 
+### Summary for Future Help-Agent Use
+
+- The biggest mental models to preserve are:
+  - contexts are first-class behavior, not decorative tags
+  - notes are workspaces, not just text documents
+  - due date and urgency are linked
+  - hidden tags can still matter
+  - several views are ranking lenses over the same work pool
+  - retrieval issues are often context, filtering, or loading issues rather than actual data loss
+
 ## Troubleshooting Checklist
 
 When a user thinks something is missing or not working, check these in order:
@@ -847,13 +903,3 @@ When a user thinks something is missing or not working, check these in order:
 6. Check whether the task belongs to an unpinned bucket or hidden system context.
 7. For stale UI behavior, try `Update App`.
 8. For persistent cache issues, use `Reset PWA`.
-
-## Summary for Future Help-Agent Use
-
-- The biggest mental models to preserve are:
-  - contexts are first-class behavior, not decorative tags
-  - notes are workspaces, not just text documents
-  - due date and urgency are linked
-  - hidden tags can still matter
-  - several views are ranking lenses over the same work pool
-  - retrieval issues are often context, filtering, or loading issues rather than actual data loss