Teams Todo: first deployed UX and sync review
Date: 2026-11-11. Status: historical investigation of the first deployed MVP. The owner reviewed and expanded these recommendations; the approved direction and active implementation checklist are now R0–R7. Findings below describe the inspected baseline, not completion of the revised work.
Subsequent approved decisions
Latest decision: SQLite with explicit semantic events replaces xitdb storage/replicas and the per-entity-signing proposal below. Direct FIPS origin attribution, receipt separate from acceptance, dependency-aware review and optional explicit agreement are now required. See the active plan; this document remains historical investigation.
The active plan supersedes the earlier open questions and automatic-edit-publication
flow in this report: ordinary owner edits save locally without drafts; Send updates
releases changes; FIPS node keys sign persisted shared data/configuration, with human
labels inferred from verified bindings. Named Create & share and direct invitations
with Accept & join integrate explicit exact-scope grant approval. list becomes
boards-only, show has a board header outside the task tree. Diagnostics/activity and
explicit clear/local-remove/fresh-board/app-reset workflows are required. The old
copyable-descriptor flow stays a manual fallback, not the primary onboarding UX.
Related: architecture, implementation/evidence record, FIPS access record.
Summary
The current app exposes its implementation steps instead of guiding someone through sharing a board. The user must coordinate identities, membership, local grants, descriptor import, drafts and sync while the UI mostly shows internal identifiers. Several intended UX features, especially the owner peer picker and actionable missing-access state, are not actually implemented as described in the plans.
There is also a concrete local blocker for the reported failed collaboration: the local installation has no Teams Todo grants and no pending access requests. Its saved error is permission denial, not a demonstrated binary replication failure. FIPS reachability alone cannot authorize app traffic.
The shortcut icon is corrected in this change. Other behavior changes below are proposals only. No grants, board data or task drafts were changed by this investigation.
Evidence and limits
Inspected source and local SQLite state read-only; no authenticated browser session, live sync attempt, VPS shell or VPS database was used. The user supplied the deployed UI observations and validation error. Local baselines at inspection:
- Core:
a6cd41ad. - FIPS:
a9c38b9, package version1.0.0. - Teams Todo:
00dbe08, package version0.0.1, plus this shortcut icon correction. - Storage dependency:
xitdb@0.30.0.
The local saved board is test, ID 9061ca26-b19b-4104-9384-89e26c232f7e,
membership revision 2, with the local node and the paired VPS node as members.
Public keys are abbreviated here; the investigation compared the full values.
| Local evidence | Observed value |
|---|---|
| Local FIPS identity | 022be41e…14e87aa; matches Teams Todo's pinned identity |
| Remote member | 021eada2…967699; matches paired node vm-2185.lnvps.cloud |
| FIPS roster status | online at inspection; not an app permission or sync result |
| Teams Todo grant records | None |
| Teams Todo access requests | None |
| Incoming subscription | false |
| Outgoing subscription | pending |
| App contact / durable sync | Both null |
| Acknowledged local bytes | 0 |
| Saved app error | No matching owner grant for this app, local identity, peer, protocol and topic. |
| Board source files | One local writer file; no remote writer replica |
| Pending drafts | One unaccepted done operation |
This establishes a local permission blocker. It does not establish the VPS's membership revision, grants, accepted task history, installed commits, or transport behavior after both sides are correctly configured. The pending completion draft is another reminder that an unaccepted operation is not a replicated edit; it is not evidence that the original add operation was unaccepted.
Findings
1. Shortcut icon used the wrong kind of identifier — fixed
definition.ts used webWidget.icon: 'checklist'. Shortcut
icons are file paths; generic WebNode toolbar icons are glyph names. Core therefore
requested /plugin-icons/teams-todo/checklist and skipped publishing that nonexistent
asset because it had no supported extension.
The shortcut now references icon.svg, the existing package icon supplied by the
user. Its expected URL is /plugin-icons/teams-todo/icon.svg. An <img> serving
that SVG is correct; inline SVG and proxy/VPN changes are unnecessary for this defect.
Targeted lint, generation and a source/path existence check passed. Deployed
confirmation still requires the updated app on each installation.
2. Creating and editing members requires implementation knowledge
definition.ts exposes member keys as a comma-separated string.
app.ts parses these keys, but supplies no actual paired-node chooser
and does not verify pairing before saving a descriptor. A syntactically valid
unknown node can therefore become a member that cannot communicate yet.
There is an important distinction:
- New board: the local creator is inserted automatically; the user does not need to paste their own key.
- Edit members: the current command replaces the entire member list and the creator must remain included. This inconsistent interaction invites mistakes.
The app's peers operation lists only already-granted peers. Before the first
board grant it cannot help select new members. The Access UI calls itself a
"paired node picker", but actually opens grant management, not a chooser.
Recommendation: an owner-initiated multi-select of paired instances, displaying local aliases, owner labels and expandable keys. Show the local node as included and fixed. Unknown/unpaired imported members should produce a specific setup issue. Keep ordinary capability peer enumeration grant-filtered; selection of ungranted nodes belongs in a FIPS-owned authenticated owner chooser, not an unrestricted app roster API. The chooser-to-app handoff needs explicit design; it is not an existing implemented capability.
3. Add grant is a raw administrative form, not board authorization
In ../../fips/commands/access/adapter.ts,
the Add grant action prepopulates peers: '[]', topics: '[]' and no protocol.
Its presentation: 'form' opens the generic command form. The access command
declares all options optional because it also handles list/remove/allow operations.
There are no action-specific required fields or useful default scope for creation.
Submitting this form reaches saveGrants with empty scope and produces exactly
the kinds of Zod errors reported by the user. These are correct denials of invalid
scope, but unsuitable user-facing validation. JSON arrays and protocol syntax
should not be required knowledge for sharing a todo board.
There is a better existing path in app.ts: Review access records
the board's exact protocol, topic and other members. FIPS can display that stored
request and Allow it without retyping anything. However, it is hidden under the
board menu, includes an extra intermediate "Review access in FIPS" screen, and is
not a step offered immediately after creating/importing the board.
The empty local request table supports that this successful request flow was not completed in the local installation; it cannot tell us every UI action attempted.
Recommendation: make board-scoped Enable sharing the primary setup action. Show a readable FIPS-owned approval for this app, these instances and this board, with technical protocol/topic details expandable. Keep approval explicit. Separate this from the advanced general grant editor; give that editor real selection controls, action-specific validation and plain-language errors. Do not add wildcard grants or app self-approval to compensate for poor forms.
4. Sharing/export is technically possible but poorly surfaced
The top-level export command needs a board ID. The board menu already supplies
the ID, so manual copying is not inherently required. However, that useful action
is hidden and app.ts returns plain JSON without a dedicated copy
control or a readable "what the other person should do" summary.
Import gives a JSON textarea, then a draft JSON preview. It does not lead the user through local access approval or present a compact readiness checklist.
Recommendation: visible Share board with Copy invitation containing the existing versioned descriptor, followed by Join board with a readable title/creator/member preview. Preserve board context throughout. Keep raw JSON export/import as a technical fallback. An encoded invitation is a convenience container, not cryptographic proof of authorship; established creator and membership review rules still apply. Automatic network invitation delivery would be separate scope because app traffic is grant-gated before joining.
5. Every task action creates a draft, including checkbox toggles
view.ts routes the checkbox to done/undone, which creates a
draft in app.ts. The displayed task changes only after acceptance.
Drafts are shown as JSON rather than "Mark task X complete". Acceptance returns
a technical text message rather than an obvious updated board result.
This makes a familiar checkbox feel unreliable even when it behaves as implemented. An unaccepted draft cannot sync. The current local pending completion is concrete evidence that draft state needs a clearer presentation.
Recommendation: at minimum, human-readable draft previews, explicit pending state on the affected task, inline Accept/Decline and an immediate board refresh. Whether explicit owner UI edits should save directly while AI/text mutations retain drafts is a product decision for review. Do not silently change the existing draft policy as part of the icon or sync fix.
6. Missing access is buried; the board summary can look successful
view.ts shows a green local saved badge whenever the local node
is a member. That condition does not inspect grants, drafts, source durability or
peer acknowledgements. The useful error is nested under Board details, then the
remote member, next to raw keys, ISO timestamps and byte counts.
There is no computed board readiness/sync model. Review access is always a menu
item rather than a conditional next action when access is missing. Peer names come
from a cached grant-filtered peer list; ungranted members can appear as truncated
keys plus unknown / no grant, conflating absence of visibility with reachability.
Recommendation: one compact primary status and next action per board, with a separate local-save/pending-draft indicator. Example states: Local only, Needs local access approval, Connecting, Waiting for peer response, Syncing, Up to date at last exchange, Offline with pending changes, or Failed with Retry/Details. Keep transport, subscription and durability distinct in the model, but summarize them for humans.
Do not claim "remote grant missing" from silence: the current protocol cannot distinguish that from a missing board, offline app or dropped message. Local grant status can be known precisely; remote setup should be described as unconfirmed until there is authenticated app evidence.
7. Background sync exists, but its state and recovery are confusing
network.ts already reconciles at startup, on connected hints,
after board configuration changes, every 60 seconds and on Sync now. A successful
setup should not require repeated manual Sync clicks.
However:
- Each subscription attempt writes
outgoing: 'pending', including periodic attempts after an earlier acceptance. On failure it records error text but leaves pending. - The connection error code is discarded in
subscribe; other send errors are flattened into strings. There is no durable structured blocked/retry state. - Grant approval does not itself notify Teams Todo or immediately resume a blocked board. Periodic reconciliation or Sync now eventually retries; connection-change hints alone cannot solve approval while the physical link is already connected.
- The list polls every five seconds.
contactanddurabletimestamps change during reconciliation; the samedurablefield records both installed remote histories and acknowledgements of local history. The UI exposes this churn as dense text. - Sync now returns Sync scheduled without explaining local preconditions or reporting later completion. A remote grant denial is silently dropped by FIPS's inbound gate, so the app can ultimately show a timeout rather than its remote cause.
- FIPS's receive dispatcher awaits the capability call but does not inspect its
acceptedresult. An app-level rejection need not yield a useful transport log.
Recommendation: structured per-board/per-peer setup and transfer states; separate last received commit, last remote acknowledgement, checked cursors and current in-flight work. Preserve stable accepted subscription state across refresh attempts, while marking stale/unconfirmed state honestly. On explicit approval completion, recheck exact local grant coverage and resume reconciliation promptly; retain periodic recovery. Represent known permission denial as blocked, not a forever-pending connection. Add bounded stage/reason diagnostics and actionable errors without inventing remote receipts or leaking unauthorized board data.
An "up to date" label must be based on validated received history and confirmed remote acknowledgement of the captured local head, scoped to reachable members and the last exchange. A successful UDP write, recent contact or scheduled job is insufficient.
8. Empty command folders are scaffold residue
The local commands/ tree contains empty directories. The active plugin imports
the flat app.ts, definition.ts, view.ts, storage.ts and network.ts files.
Empty directories are not tracked by Git and do not explain the published icon or
permission failure. The flat layout is viable for this MVP. Cleanup can be considered
separately; this investigation did not delete directories or data.
Proposed user experience for review
For already-paired instances, the normal experience should be:
Creator: New board → enter title and select named instances → review/save board → Enable sharing with prefilled owner approval → Copy invitation.
Other instance: Join board → paste invitation → review title/members and accept → Enable sharing with prefilled owner approval → automatic sync.
Local task edits remain usable during setup/offline periods. Each board should show its remaining setup action at the top. No normal board flow should require typing protocol names, topic UUIDs, grant JSON arrays or a local FIPS key. Pairing and each instance's access approval remain real, explicit responsibilities, but their presentation should be guided and contextual.
A compact visual structure to discuss before implementation:
Work board Needs local access approval [Enable sharing] [Share] [⋮]
Saved locally · 1 change awaiting peer acknowledgement
[ Add a task… ] [Add]
□ Task title [⋮]
Members: This instance, My VPS
[Details: per-peer status, history and technical identifiers]
Primary actions should be visible labels, not only hover controls. Raw keys, byte cursors, protocol IDs and Lamport history belong under Details. Reuse generic forms, choices and tree primitives in compact terminal styling; keep app-specific UI in the plugins.
How to separate the current blocker from later sync defects
The next user-assisted verification should start from the existing board, not recreate identities, delete histories or change the transport:
- Check both installations have the same board ID, creator and membership revision; confirm the task add draft was accepted on its origin.
- On each instance, open the board-scoped Review access flow and approve its stored
request. Protocol is
teams-todo.sync.v1, topic is this board ID and peer scope contains the other instance's exact FIPS key. Verify the saved grant exists. - Reconcile and inspect both directions: subscription result, sync-start/chunks, replica commit and matching acknowledgement. Record which stage first fails.
- If permission denial disappears but no app response arrives, collect both sides' installed commits and correlated FIPS/app errors. Then investigate transport, board authorization, payload handling or Linux storage based on that evidence.
- After a successful initial exchange, check restart/offline catch-up separately.
These steps are proposed verification, not actions already performed by the agent. No conclusion about working cross-OS binary replication follows from fixing grants.
Decisions needed before an implementation plan
- Confirm the guided create/join/share flow and compact board status layout.
- Decide the manual-owner task edit policy: improved inline draft review or direct UI saves with drafts retained for automation/text commands.
- Decide whether a copyable board invitation is sufficient for the next UX slice; automatic delivery requires additional onboarding design.
The recommended technical focus is actionable local grant setup and truthful sync state, alongside the member chooser and human-readable board/draft UI. Transport or storage replacement is not justified by the current failure evidence.