TasGrid/docs/HELP_GUIDE.md

# TasGrid Reference Guide

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.

## 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.
- It excludes SDK, API, and integration-developer documentation.
- It also excludes developer-only migration tools, admin repair flows, and hidden legacy UI that is not active in normal use.

## Core Mental Model

- TasGrid is built around tasks, notes, and contexts.
- Tasks are the primary work items.
- Notes are rich project workspaces that can hold content, tabs, linked tasks, and public share links.
- Contexts decide where work lives and who can see or act on it.
- Contexts are usually represented through special tags:
  - `@person` for a user's personal context
  - `@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

### Main App Modes

- TasGrid has two main modes: `Tasks` and `Notes`.
- The top-center mode switcher toggles between them.
- On desktop, switching modes changes the main sidebar content.
- On mobile, Notes opens into a note-list-first flow and hides the bottom navigation while you are inside the note workspace.

### Desktop Navigation

- The left sidebar provides task views:
  - `Focus`
  - `Urgency`
  - `Priority`
  - `Matrix`
  - `Snowball`
  - `Dig In`
  - `Progress`
- 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`
  - 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.
- Mobile Help is available through `Settings > Resources > Help`.
- 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>`.

## Task Creation and Editing

### Task Creation

- The main task creation flow is Quick Entry.
- Users can open Quick Entry with:
  - the floating `+` button
  - `Ctrl+K` or `Cmd+K`
- Quick Entry requires:
  - `Title`
  - `Priority`
  - `Urgency`
- Optional fields include:
  - `Size`
  - `Due Date`
  - tags
  - rich description/content
  - template selection

### Default Task Values and Interpretation

- Size defaults to `3`, which represents about one hour of work.
- If a task is created with urgency but no due date, TasGrid derives the due date from the urgency setting.
- Due date and urgency are linked concepts in the task model.
- Creating a task inside an active context often causes TasGrid to inherit that context automatically.
- Common examples:
  - creating a task while switched into a bucket adds that bucket context
  - creating a task while in a supervised user context applies that personal context
  - creating a task from a note applies the note's `#note` tag

### Quick Entry Shorthand

- Quick Entry supports shorthand text commands:
  - `/pN` to set priority
  - `/uN` to set urgency
  - `/t tag` to add a tag
  - `/t tag:5` to add a tag with a score/value
- This lets users create and classify tasks quickly without manually touching every field.

### Task Detail Editing

- Opening a task shows the main task detail editing sheet.
- Users can edit:
  - title
  - status
  - priority
  - urgency
  - size
  - due date
  - tags
  - favorite state
  - 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

- Task cards support quick actions without opening the full editor.
- Common actions include:
  - open the task
  - change status
  - complete the task
  - duplicate the task
  - toggle favorite
- Double-clicking a task can complete it quickly.
- 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`.
- `0` is the starting state.
- `10` is complete.
- Progress-oriented views sort tasks using status plus other ranking signals.
- Recurring tasks that are completed may show a progress ring while waiting to reopen.

### Due Date, Urgency, Priority, and Size

- `Priority` and `Urgency` both influence ranking, but they are not the same thing.
- `Urgency` is closely tied to due date behavior.
- `Size` affects how some views rank or group work.
- The app calculates combined scores from these factors for several list views.
- Users often expect these values to be fully independent, but due date and urgency especially are coupled.

### Favorites

- Favoriting a task is personal to the current user.
- Internally, favorites are handled with hidden per-user tagging behavior.
- A task being starred by one person does not automatically mean it is starred for everyone else.

### Task Deletion, Trash, and Auto-Maintenance

- Deleting a task is a soft delete, not an immediate permanent delete.
- Soft-deleted tasks go into Trash for 7 days.
- The app usually offers an immediate undo prompt after deletion.
- Permanent recovery and permanent delete are available in `Settings > Trash`.
- Trash is automatically purged on app load when items have exceeded the 7-day retention window.

TasGrid also performs maintenance-related auto-trash behavior:

- completed tasks older than 90 days are automatically moved to trash
- tasks with no active personal, shared, or note-linked context can be auto-trashed during initialization

These behaviors are important because a user may feel a task has disappeared when it has actually moved to Trash automatically.

### Recurrence

- Tasks support recurring schedules.
- Supported recurrence types are:
  - daily
  - weekly
  - monthly
- Weekly recurrence requires selected days.
- Monthly recurrence depends on a valid day-of-month configuration.
- Completed recurring tasks do not stay permanently complete. TasGrid reopens them when their next recurrence window arrives.
- Reopen checks happen on startup and continue periodically while the app is running.

### Task Templates

- Task templates let users store reusable task setups.
- Template fields include:
  - template name
  - title placeholder
  - priority
  - urgency
  - tags
  - rich description/content
- Notably, task templates do not include:
  - size
  - explicit due date
- When a template is applied, due date is recalculated from urgency rather than copied as a fixed old date.

### Task Import

- Settings includes an `Import Tasks` tool for pasting in task lists.
- The import flow is:
  1. paste a task list
  2. review parsed tasks
  3. apply bulk defaults
  4. import
- The parser strips common list formatting such as:
  - bullets
  - checkboxes
  - numbered-list prefixes
- Each non-empty line becomes one task.
- Users can bulk-apply:
  - priority
  - urgency
  - size
  - tags
- Users can still edit or remove individual rows before import.
- If no tags are provided, imported tasks default to `work`.
- Due date is derived from urgency on import just like normal task creation.

## Task Views

### Focus

- Focus is the main ranking-oriented list view.
- It sorts by a combined score using the task's importance and urgency characteristics.
- This is often the default working view for deciding what deserves attention next.

### Urgency

- Urgency emphasizes time pressure.
- It sorts by a continuous urgency score and then falls back to other ranking signals.
- It is helpful when due dates and near-term deadlines matter more than task size or stage.

### Priority

- Priority is intended as an importance-oriented lens.
- In the current implementation, it is not meaningfully different from Focus in the way tasks are sorted.
- This is an important documentation caveat because users may expect a completely different ranking.

### Progress

- Progress groups and ranks work based on completion state first, then other score factors.
- It is useful when users want to move partially completed work forward rather than start new tasks.

### Snowball

- Snowball sorts by smaller tasks first.
- It is the "quick wins" view.
- This is useful when users want momentum, cleanup, or rapid visible progress.

### Dig In

- Dig In sorts by larger tasks first.
- It is the "deep work" view.
- This is useful when users want to tackle heavier tasks rather than clear short items.

### Matrix

- Matrix shows tasks on an urgency-versus-priority grid instead of a simple ranked list.
- Matrix points are clickable and expose more detail on hover or selection.
- Matrix communicates multiple dimensions:
  - placement reflects urgency and priority
  - dot size reflects task size
  - dot color communicates ranking/meaning in the current matrix logic
- Tooltips surface key values such as urgency, size, and priority.
- Matrix includes time-scale controls:
  - `1`
  - `7`
  - `30`
  - `60`
  - `90` days
- Changing the time scale changes how the urgency side of the visualization is interpreted.

## Search, Filters, and Saved Filters

### Task Search and Filters

- Task filtering supports:
  - text query
  - included tags
  - priority ranges
  - urgency ranges
  - edited today
  - mine
  - starred
- Included tags use OR-style logic, not strict AND-only matching.
- Hidden system tags may not appear in the filter picker unless searched explicitly.
- `Mine` is based on personal-context access rules rather than just simplistic creator matching.

### Saved Task Filters

- Users can save the current task filter setup as a reusable filter template.
- Saved filters are managed from the filter/search area rather than from Settings.
- These are useful for repeat operational views like:
  - follow-up work
  - specific team contexts
  - daily supervision checks

### Note Filters

- Notes also have filter templates, separate from task filter templates.
- They are managed in Notes mode through the note filter/search UI, not through Settings.

### Load All

- `Load All` is used when older completed or historical items are not currently loaded into the active store.
- 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 and Sharing

### Context Types

- TasGrid has three important context types:
  - personal user contexts through `@person`
  - shared bucket contexts through `@bucket`
  - note contexts through `#note`
- These are system-backed contexts, not ordinary decorative tags.

### My Bucket and Personal Contexts

- Every user effectively has a personal working context.
- This is often represented in UI as `My Bucket`.
- Personal context affects what a user considers their own active work.
- Tasks can move into or out of a user's personal working space through context policies.

### Context Switcher

- The context switcher is how users move between available working spaces.
- It can show:
  - `My Bucket`
  - pinned shared buckets
  - supervised personal contexts shared with the current user
- 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.
- A bucket includes:
  - required name
  - color
  - optional description
- New buckets default to `handoff` policy.
- Bucket rows support:
  - inline rename
  - policy toggle
  - pin/unpin
  - archive
- Archiving a bucket sets a deleted timestamp on the bucket context.
- There is no confirmed user-facing bucket restore flow at this time.

### Pinned Buckets

- Pinning a bucket adds it to the context switcher.
- Pinning is stored in user preferences.
- When a bucket is pinned, TasGrid loads tasks already tagged with that bucket into the local task store.
- This matters because unpinned bucket work may not appear in the same way during task search or cross-linking flows.

### Sharing Model

- TasGrid's main sharing workflow is tag-driven.
- Users share tasks by applying:
  - an `@person` tag
  - 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:
  - `Collaborative`
  - `Handoff`
- Collaborative means a task stays visible in both places as shared work.
- Handoff means responsibility shifts between contexts in a more directional way.
- Users can define personal user-tag policies in Settings.
- Buckets also carry a policy.
- These policies strongly affect whether a task feels shared, moved, or reassigned.

### Supervision

- Supervision lets one user enter another user's personal context.
- This is broader than sharing a single task.
- Personal Context Supervision settings let a user grant specific people permission to switch into that full personal context.
- `Personal Contexts Shared With You` lists supervised contexts the current user can access.
- Supervised contexts appear in the context switcher alongside buckets.

### Hidden System Tags

- 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

- Creating work from the current context usually applies that context automatically.
- Context affects what tasks a user can see in a given working view.
- If work appears to vanish after sharing, switching context, or linking to notes, the cause is often context visibility rather than deletion.
- Users should check:
  - current context
  - active filters
  - trash
  - whether the task belongs to an unpinned bucket

## Notes Basics

### Notes Mode

- Notes is a full working mode, not just an attached notes panel.
- Switching into Notes triggers note metadata loading.
- Desktop replaces the normal task sidebar with a notes sidebar.
- Mobile shows the notes list first, then opens the editor as a layered workspace.

### Notes Sidebar

- The main notes sidebar lists root notes only.
- Child tabs do not appear in the main sidebar list.
- The sidebar supports:
  - title-and-tag search
  - saved filters
  - starred filter
  - edited today filter
  - owned by me filter
  - Prism job note filters where applicable
- Notes are sorted by title descending, not by most recently updated.

### Note Loading Model

- Notes load in two stages:
  - metadata first
  - full content when the note is opened
- This allows the notes list to appear before every note body has loaded.
- If a note is visible in metadata but restricted by visibility rules, its content may fail to hydrate for the current user.

### Creating Notes

- Creating a note from the sidebar produces a root note with:
  - title `New Note`
  - empty content
  - empty tags
  - `isPrivate: false`
  - a generated normalized key with a timestamp suffix

### Editing Notes

- Root note titles are editable inline in the note header.
- Selected child tabs can also be renamed inline.
- Note content auto-saves on a 500ms debounce.
- Leaving a note flushes pending saves immediately.

### Deleting and Restoring Notes

- Deleting a note is a soft delete.
- Soft delete:
  - sets `deletedAt`
  - removes current selection
  - shows an Undo toast
- Restore is available from:
  - the immediate Undo action
  - `Settings > Trash`
- Permanent delete is exposed from `Settings > Trash`.
- Permanent deletion also removes note references from tasks by clearing:
  - matching `#note` tag
  - matching `noteRefs`
  - matching note-based `shareRefs`

## Note Sharing and Linked Work

### Public, Private, and Share Links

- Notes can be public or private.
- Metadata loading exposes:
  - public notes
  - private notes owned by the current user
- Privacy, share-link, and delete controls are owner-only.
- Favorites can still be toggled from the note header.
- Share Link copies an embed URL like `#/embed/notes?noteId=...`.
- 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

- Root notes can have child tabs.
- Child tabs are separate note records tagged with `child-of-{rootId}`.
- The root note appears in the tab UI as `General`.
- Desktop shows tabs as draggable side ribbons.
- Mobile shows tabs in a dropdown.
- Tab order is stored through `taborder:{index}` tags.
- Dragging tabs updates those tags.
- Creating a tab makes a note with:
  - title `New Tab`
  - empty content
  - empty linked tasks array
  - `child-of-{rootId}` tag
  - privacy copied from the root note at creation time

Important privacy caveat:

- child tabs inherit privacy when they are created
- later privacy changes on the root note do not automatically cascade back down to existing child tabs

### Linked Tasks

- Notes can act as project workspaces through a linked tasks panel.
- Linked tasks belong to the note workspace.
- If the user is inside a child tab, linked tasks resolve through the parent/root note workspace.
- 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:

- create a new task from the note
- search and link an existing task
- open a task from the linked task panel

Linking constraints:

- existing-task search returns nothing until the user types
- search matches task title only
- results are capped at 10
- deleted tasks are excluded
- tasks from only unpinned buckets are excluded

Current behavior caveats:

- child tabs cannot directly unlink tasks
- unlink behavior is not perfectly consistent across every tag-linked path

### Note Rename Propagation

- Renaming a note updates both:
  - the note title
  - the normalized note key
- 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 Basics

### Shared Editor Model

- Tasks, notes, and task templates all use the same rich editor system.
- The editor supports both simple writing and structured embedded content.

### Basic Content Types

- Supported content includes:
  - paragraphs
  - headings 1 to 3
  - bullet lists
  - checklists
  - multi-checklists
  - code blocks
  - blockquotes
  - horizontal rules
  - links
  - highlight
  - underline
  - text alignment
  - tables
  - images
  - videos
  - file attachments
  - job file embeds
  - `@user` mentions
  - `#note` mentions

### Toolbar and Slash Commands

- The editor provides a persistent text formatting toolbar.
- When the cursor is inside a table, a table toolbar appears.
- The placeholder text is `Type '/' for commands or start writing...`.
- Typing `/` opens the slash command menu.

Available slash commands include:

- Text
- Heading 1
- Heading 2
- Heading 3
- Bullet List
- Checklist
- Multi Checklist
- Code Block
- Blockquote
- Upload
- Job File
- Divider
- Table
- Delete Table

- Slash command filtering is prefix-based against titles and aliases.
- The note header also provides shortcut buttons for `Commands` and `Upload`.

### Mentions

#### `@user` Mentions

- `@user` suggestions come from user share contexts.
- The current user's own context is excluded from suggestion results.
- Matching is based on the start of the display name.
- In task detail, inserting an `@user` mention also applies the corresponding `@user` tag for sharing behavior.

#### `#note` Mentions

- `#note` suggestions include root notes only, not child tabs.
- Matching uses note key or title substring behavior.
- If note content is already loaded, the suggestion list can show a short preview.
- Clicking a `#note` mention opens a preview popover with:
  - note title
  - short content preview
  - `Open Note`

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:
  - the Upload button
  - the slash menu
  - paste
  - drag and drop
- Uploading requires an active task or active note.

Upload result behavior:

- images become inline image blocks
- videos become inline video blocks
- other files become attachment blocks

- Most image uploads are converted before upload.
- Explicit Upload command flows insert a blank paragraph afterward so the user can continue typing.
- Removing an embedded file or media block deletes it from the editor HTML.
- When leaving a note, TasGrid checks for orphaned uploads and removes no-longer-referenced files from storage.

### Images

- Images render as inline block nodes.
- They support:
  - resize handle
  - delete overlay
  - fullscreen preview
- Fullscreen preview supports:
  - zoom by click
  - wheel zoom
  - panning while zoomed

### Videos

- Videos render inline with:
  - native playback controls
  - resize handle
  - delete overlay

### File Attachments

- PDFs and `.txt` files can render inline in an embedded viewer.
- Other file types show as attachment cards with filename and open-in-new-tab behavior.
- If the first content block in a note is a PDF attachment or a job file viewer, the note uses a top-viewer layout with a large embedded viewer area.

### Tables

- Tables are inserted as 3x3 by default with a header row.
- They are resizable and selectable as editor nodes.
- The table toolbar supports:
  - insert row above
  - insert row below
  - delete row
  - insert column left
  - insert column right
  - delete column
  - merge cells
  - split cell
  - toggle header row
  - delete table

### Job File Embeds

- The editor supports Prism job file embeds through the `/job file` command.
- If a job file block has not been configured yet, it shows a picker UI.
- The picker tries to infer a job from the active note or one of its ancestor notes using a `job_id:` tag.
- If no job is detected, the user can search `Job_Info_Prod` by:
  - job number
  - job name
- Exposed file categories include:
  - `plans`
  - `EST_and_CO`
  - `Addendums`
  - `files`
- Selecting a file stores:
  - `jobId`
  - `collectionId`
  - `filename`
- The final embedded viewer uses the PocketBase file URL inside an iframe-style viewer.

## Settings

### Account Header

- Settings shows the signed-in email at the top.
- It also includes:
  - theme toggle
  - `Sign Out`

### Theme

- The theme system supports:
  - `light`
  - `dark`
  - `system`
- Theme preference is stored in local storage under `tasgrid-theme`.
- `system` is resolved from the browser or device `prefers-color-scheme`.
- The current Settings UI exposes only a visible light/dark toggle.
- Documentation should not promise a visible full theme selector with a dedicated system option unless that control is added later.

### Sharing Settings

- `Tag Sharing` explains the main context types:
  - `@person`
  - `@bucket`
  - `#note`
- `User Tag Policies` lets users decide whether each personal user context behaves as:
  - `Collaborative`
  - `Handoff`
- This section reflects the current tag/context-based sharing model.

### Supervision Settings

- `Personal Context Supervision` lets a user grant specific people access to switch into that user's personal context.
- `Personal Contexts Shared With You` shows the contexts the current user can supervise.
- These settings are separate from normal task-by-task sharing because they apply to the whole context.

### Shared Buckets Manager

- `Shared Buckets` is the bucket management area.
- Users can:
  - create buckets
  - rename buckets
  - pin buckets
  - toggle bucket policy
  - archive buckets
- Bucket creation requires a name and supports color plus optional description.

### Tag Manager

- `Tag List` is where users manage normal custom tag definitions.
- Users can:
  - rename a custom tag
  - recolor it
  - rescore it from `0` to `10`
  - delete it
- Renaming a tag propagates to tasks that use it.
- Deleting a tag removes it from tasks that use it.
- `System Tags (Users, Buckets & Notes)` is a separate expandable area.
- System tags are primarily reference/configuration artifacts tied to contexts and notes rather than standard freeform tags.

### Templates Manager

- `Task Templates` in Settings is the template management surface.
- Users can create, rename, edit, and delete templates there.
- Saved task and note filters are not managed in this section.

### Trash

- Trash contains separate lists for deleted tasks and deleted notes.
- Entries show the number of days remaining in the 7-day retention period.
- Each entry supports:
  - recover
  - permanent delete
- The Trash view is the main long-term recovery surface for deleted content.

### Update App

- `Update App` checks the service worker for updates.
- If an update is available, TasGrid reloads into the new version.
- If no update is found quickly, the app shows `No update found`.

Background update behavior:

- checks roughly hourly
- checks again when the window regains focus or visibility
- if an update is ready, it can apply automatically when the app is hidden or after about 10 minutes of idle time

### Reset PWA

- `Reset PWA` unregisters service workers, clears browser caches, and reloads the app.
- This is a repair tool for stale or broken cached app behavior.
- It should be used when the app seems out of sync, stale, or stuck, not as a normal daily action.

## Progressive Web App Behavior

### Installation

- TasGrid is configured as a PWA with standalone display behavior.
- Installation is browser-driven.
- There is no confirmed custom in-app install prompt flow.
- Users should install using the browser's own `Install App` or `Add to Home Screen` controls.

### Offline and Cached App 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.

## 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.
- Search is only as complete as the currently loaded data set.
- `Load All` may be necessary to find older completed work.
- Notes search does not search full note body text. It searches title and tags.
- The notes list does not include child tabs.
- Linking existing tasks from a note uses task title search only and returns at most 10 results.
- Task-link suggestions exclude tasks that belong only to unpinned buckets.
- Child note tabs inherit privacy only when created, not continuously afterward.
- Private note share links require the note to be made public before other users can view them.
- Trash is auto-purged after 7 days on app load.
- Completed tasks older than 90 days can be auto-moved to trash.
- Some tasks with no valid active context can also be auto-trashed.
- 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.

## Reference Notes

### Explicit Exclusions

- SDK and API documentation
- integration-developer workflows
- dev-data migration tools
- production migration tools
- 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:

1. Confirm whether they are in `Tasks` or `Notes`.
2. Confirm the active context in the context switcher.
3. Check active filters and whether a saved filter is still applied.
4. Use `Load All` if the issue may involve older items.
5. Check whether the item is in Trash.
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`.