Skip to content

Project-first dashboard IA: obvious creation, Connections cleanup, Armonia sidebar merge #202

Closed

Description

@kateebonner

Important

Problem

Creating a project is buried (a small folder-add affordance that only registers an existing directory — there is no true "create"), and the surrounding chrome misnames what it holds: "Sessions" presents a global flat list of what are really per-project children, "Connections" now holds only execution targets, the defaults capsule claims "Session defaults" for global choices, and the native sidebar shows two placeholder trees ("Vault", "Armonia") for the same concept. Aaron's live-demo feedback: creation must be obvious, the sidebar redundancy must go, and there is no direct way to launch the chat from the sidebar.

Approach

Make Project the organizing noun. The dashboard grows a first-class New project flow (true creation: name + location → directory created, git-initialized, registered, first session opened). The chrome renames the surfaces whose names are wrong — Projects (creation + project list with sessions nested inside) and Defaults (honest copy for the global model + solver pair) — and trims the Connections surface (drop its Vaults tab; the name is already glossary-correct). The native sidebar collapses the two placeholder trees into one Armonia panel (mounted Vaults as its roots, product empty-state copy) and gains an always-visible Open Amico Chat launch action. Key reason: every surface gets exactly one job, and creation lands where a first-time user is already looking.

Approaches Considered

  • Register-only creation surfaced bigger — rejected: "create" stays a lie for users who arrive without a folder (hackathon persona).
  • Full scaffold at creation (Julia env, vault wiring) — rejected: onboarding commands own environment setup; keeps the dialog light.
  • Keep "Sessions" flat with project group headers — rejected: the top-level noun stays wrong; switching is by project.
  • Coin "Workspace" as a new term — rejected: collides with VSCode's own term in the same window; Project suffices.
  • Name the merged sidebar panel "Vaults" — rejected: Armonia is the system, a Vault is one tier in it; the panel is the system, its roots are the Vaults.
  • Rename Connections → Devices — rejected (review panel + glossary): the surface lists Connections, not Devices; the rename would put the wrong noun on it. A surface that actually lists devices is a possible follow-up.
  • Project-first chrome + true creation + sidebar merge under Armonia (chosen) — one job per surface, creation at point of attention, brand on the panel and plain words in its empty state.
  • Per-session solver/model overrides — rejected (YAGNI): global Defaults + per-solve Routing confirm already give two honest levels.

Scope

In (slice 1 — chrome, fork): Projects menu (top action: New project; project list, current marked; each project's recent sessions nested, overflow to all; orphan sessions grouped under their raw directory path so nothing becomes unreachable) · New-project hero action in the dashboard body's project area · creation dialog (Name → slugified folder preview; Location with remembered parent; "Open existing folder instead…" secondary; mkdir → git init → register → open first session; inline errors for name collision / unwritable location) · Connections popover: Vaults tab removed (name unchanged; Pasqal card unchanged) · defaults capsule copy → "Defaults — model & solver, apply everywhere".
In (slice 2 — sidebar, extension): merge the two placeholder trees into one Armonia panel (mounted Vaults as root nodes; empty-state copy "Your vaults collect here" plus a set-up-a-vault action, until ArmoniaService lands) · an always-visible Open Amico Chat action on the amicode sidebar container (a view/title action, not empty-only welcome content) · CONTEXT.md gains Project, Session, Armonia, Vault entries.
Out: per-session solver/model overrides — Routing covers per-solve choice. · Vault surface redesign beyond the merge (real mount rendering awaits ArmoniaService) — separate design. · Session-view left rail — different view, works as is. · Light-mode code-block contrast — already fixed (inline-code chip, merged this morning). · Creation-time scaffolding beyond git init — onboarding commands own it. · Catalog view — unchanged, stays its own tree.

Assumptions / Open Qs

  • Sidebar panel keeps the brand name Armonia; the empty state names what collects there ("Your vaults collect here"). Resolved with Kate; Aaron may refine the exact copy in review.
  • Assumes the existing directory-picker and edit-project dialogs are reused as-is for "Open existing" and per-project actions.
  • Open: default parent directory for a first-ever creation (proposal: ~/AmicodeProjects, remembered thereafter).

Acceptance Criteria

  1. The dashboard body's project area shows a first-class New project action; activating it (or the Projects menu's top item) opens the creation dialog.
  2. Creating with a valid name + location: the directory exists on disk, is git-initialized, appears registered in the Projects menu, and a first session opens in it — no palette or external file manager involved.
  3. Name collision and unwritable location each produce an inline, recoverable error, and no partial directory is left behind.
  4. A git-init failure or absent git does not block creation: the project is still created, registered, and opened, with a non-blocking notice that change tracking is unavailable.
  5. "Open existing folder instead…" inside the dialog reaches the current directory-picker flow unchanged.
  6. The chrome entry formerly "Sessions" is Projects: lists projects with the current one marked; each project shows its recent sessions nested with an overflow to the full list; selecting a session opens it exactly as before.
  7. Sessions whose directory matches no registered project remain reachable, grouped under their directory path.
  8. The Connections popover no longer contains a Vaults tab; its name and the Pasqal card are unchanged.
  9. The defaults capsule's copy no longer says "Session defaults"; it presents the pair as global defaults.
  10. The native sidebar shows exactly one knowledge panel, named Armonia, whose roots are the mounted Vaults and whose empty state reads "Your vaults collect here" (or equivalent); no separate "Vault" view remains, and Catalog stays its own view.
  11. The amicode sidebar shows an always-visible Open Amico Chat action that opens the chat webview.
  12. Existing user state is untouched: registered projects, session bindings, model pin, and solver mode survive the update with no migration.

Key Decisions

  • Creation is directory-level: name + location, then a best-effort git init (change tracking from minute one). Git is an enhancement, not a requirement — if git is absent from PATH or init fails, the project is still created and registered without it, with a non-blocking notice; the atomic unit is {directory created + registered}, and git layers on top. No environment scaffolding.
  • Nesting is presentation only: sessions keep their existing directory binding; no session data is re-keyed (AC12 is the invariant).
  • No surface is renamed to a term it does not denote: the Connections popover keeps its glossary-correct name (it lists Connections; a device-listing surface is deferred). Project, Session, Armonia, Vault are added to CONTEXT.md and ride with slice 2.
  • The webview Vaults tab is deleted (not moved): the native Armonia panel + existing vault commands are the canonical vault surfaces.
  • The sidebar launch affordance is a view/title action (always visible) rather than welcome content (shows only when empty) — Aaron's complaint was that no launch button was reachable.
  • Slices land independently: chrome (fork) and sidebar (extension) are separate PRs; either is shippable alone.

Constraints & Invariants

  • No session may become unreachable from the Projects menu under any registration state.
  • Creation is atomic for the {directory + registration} unit: a pre-creation failure (name collision, unwritable location) leaves nothing on disk and registers nothing; git init is best-effort layered on top and never leaves the project half-registered.
  • Copy-only changes (Defaults label) must not touch stored state or settings keys.
Prior Art / Patterns
  • The directory-picker + register flow ("open project") — reused verbatim as the dialog's secondary path.
  • The edit-project dialog — reused for per-project actions in the Projects menu.
  • The status-popover tab structure — the Connections surface keeps it, minus the Vaults tab.
  • The solver-toggle accordion (amicode#200) — precedent for disclosure grammar in the chrome (radios choose, kebab discloses, click-out dismisses).
  • VSCode menus: view/title — always-visible sidebar action for the launch button; viewsWelcome for the Armonia empty state's set-up-a-vault link.
  • The existing placeholder trees + SessionCatalogTree in the extension's tree providers — the merge collapses two of the three.

Source

Design session Kate Bonner + Claude, 2026-07-22 — grilled via grill-with-docs; CONTEXT.md gains Project, Session, Armonia, Vault entries (same PR as slice 2). Origin: Aaron Trowbridge's live-demo feedback (sidebar redundancy, no launch button, buried creation) + amicode#200's chrome cleanup. Related: amicode#200 (solver toggle owns its connection), UX track #46–#53.

Notes

Multi-slice: after publish, decompose via break-into-subissues (slice 1 = chrome/fork, slice 2 = sidebar/extension). The default parent directory is the one remaining review-time knob; the Armonia name and empty-state copy are resolved but open to Aaron's polish.

Activity

  1. kateebonner commented on Jul 23, 2026

    @kateebonner
    ContributorAuthor

    Both slices merged: #203 via harmoniqs/opencode#46 (chrome/creation) and #204 via #205 (Armonia sidebar + launch). CONTEXT.md glossary (Project, Session, Armonia, Vault) landed with #205.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions