From e615e8323a3ede766bcbff5d4be805486e8674a3 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 16 Jul 2026 00:37:38 +0000 Subject: [PATCH 1/5] docs: add 4C Shade product docs + HH Shade instance memory - docs/4c-shade/: vision brief, decision log, licensing & entity structure, index - CLAUDE.md: HH Shade project memory (force-tracked; upstream gitignored it) - docs/hh-shade/CONTEXT.md: instance context (Dibbits build, sibling repos, alpha status) Establishes this repo's identity as HH Shade, the Hardscape House deployment of 4C Shade (by 4C Digital). No platform/source changes. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01Wi5ywDCQ3PytwHmBXdNmhp --- CLAUDE.md | 31 +++++++++ docs/4c-shade/DECISION-LOG.md | 47 ++++++++++++++ docs/4c-shade/LICENSING-AND-ENTITY.md | 57 ++++++++++++++++ docs/4c-shade/README.md | 19 ++++++ docs/4c-shade/VISION-BRIEF.md | 93 +++++++++++++++++++++++++++ docs/hh-shade/CONTEXT.md | 37 +++++++++++ 6 files changed, 284 insertions(+) create mode 100644 CLAUDE.md create mode 100644 docs/4c-shade/DECISION-LOG.md create mode 100644 docs/4c-shade/LICENSING-AND-ENTITY.md create mode 100644 docs/4c-shade/README.md create mode 100644 docs/4c-shade/VISION-BRIEF.md create mode 100644 docs/hh-shade/CONTEXT.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000000..7168522dbb0 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,31 @@ +# CLAUDE.md — HH Shade (project memory) + +Guidance for Claude Code sessions working in this repository. + +## What this repo is + +This is **HH Shade** — the **Hardscape House** deployment of **4C Shade**, an owned, self-hosted, QMS-gated, agent-native software-delivery platform built by **4C Digital**. The repo currently holds an upstream **Huly platform fork** being repurposed into the Shade backbone (alpha). + +- **Product docs:** [`docs/4c-shade/`](docs/4c-shade/) — start with [`VISION-BRIEF.md`](docs/4c-shade/VISION-BRIEF.md). +- **This instance's context:** [`docs/hh-shade/CONTEXT.md`](docs/hh-shade/CONTEXT.md). +- **Note:** the existing root `AGENTS.md` is upstream Huly's, not Shade's — this `CLAUDE.md` is the Shade project memory and takes precedence for Shade work. + +## Identity stack + +**4C Digital** (owner) · **Shade** (platform) · **4C Shade** (product) · **` Shade`** (this = **HH Shade**; also FB Shade, Dibbits Shade…) · **Prism** (native OSS coordinator agent) · **ShadeOS** (doctrine/heritage) · **4CDAI** (optional AI-division banner). + +## Development + +- **Branch:** develop on `claude/dibbits-workspace-consolidation-69sqj8`. Commit with clear messages; push with `git push -u origin `. Do **not** push to other branches without explicit permission. +- **Repo rename:** slated to become `hh-shade` (GitHub slugs can't contain spaces; display "HH Shade"). Done via GitHub Settings. + +## Build guardrails (from the vision brief) + +- **Agent skills = quality over quantity.** The 26 ShadeOS crew ops are *source material, not a port list*. Curate a lean, high-value skill set; add capabilities deliberately as each earns its place. Do **not** overbloat the Claude-facing agent tooling. +- **Most-permissive licensing.** Prefer MIT/Apache/BSD for anything forked/embedded/shipped/hosted-for-others; EPL/MPL acceptable (weak, file-level); **avoid AGPL** for shipped/hosted components. Tools you merely *run* are unconstrained. See [`docs/4c-shade/LICENSING-AND-ENTITY.md`](docs/4c-shade/LICENSING-AND-ENTITY.md). +- **Subscription-first agents.** Run the official `claude` CLI on the subscription (interactive in a terminal, or headless via `CLAUDE_CODE_OAUTH_TOKEN`); avoid `ANTHROPIC_API_KEY`/`--bare` metered paths except for deliberate bursts. +- **The 5 gates** (human sign-offs, first-class): G-DESIGN, G-LOCK, G-PUSH, G-CLIENT, G-MONEY. + +## Scope discipline + +The full plan spans a **product build** (4C Shade: backbone + console) and the **Dibbits consolidation** (running the Dibbits/HardscapeOS build on this HH Shade instance). Confirm which layer a task belongs to before large changes. Deferred (not current): fork-source archival, the custom MCP server, migration scripts, the custom console — unless a task explicitly calls for them. diff --git a/docs/4c-shade/DECISION-LOG.md b/docs/4c-shade/DECISION-LOG.md new file mode 100644 index 00000000000..8bfc9fa7d61 --- /dev/null +++ b/docs/4c-shade/DECISION-LOG.md @@ -0,0 +1,47 @@ +# 4C Shade — Decision Log + +*Condensed record of decisions made during the 4C Shade discovery/vision sessions. Newest context wins; this is the reference companion to `VISION-BRIEF.md`.* + +--- + +## Locked decisions + +| # | Decision | Rationale | +|---|---|---| +| D1 | **Backbone = self-hosted Huly (EPL-2.0)** | Licensing-validated as the most-permissive *genuinely-capable* PM+KB+QMS+multi-workspace platform; every all-in-one alternative is AGPL or source-available. Unique controlled-docs/QMS. | +| D2 | **Product = "4C Shade"** (by 4C Digital) | Keeps the `Shade` family (ShadeOS heritage, ` Shade` instances); leaves "Prism" free as the coordinator agent. | +| D3 | **Naming = ` Shade` convention** | White-label native — every deployment carries the customer's name (FB Shade, HH Shade, Dibbits Shade…). | +| D4 | **Cockpit (interim) = standard Claude CLI + MCP, hosted in Zed** | Minimum complexity; subscription-preserving; MCP is the integration bus. Orchestrators (Conductor/Claude Squad) deferred, no rework to adopt later. | +| D5 | **Console + backbone BOTH in scope** | Console (embedded terminal/browser, agent-manager) is the product's face; built demo-first, single cutover. | +| D6 | **"Most permissive possible" licensing driver** | Permissive inputs (EPL-Huly + Apache/MIT models), 4C-owned controlled output. AGPL disqualifying for anything forked/hosted-for-others. | +| D7 | **Local coordinator model = gpt-oss-120b or Qwen3-30B-A3B (Apache-2.0)** | Best tool-calling per VRAM-dollar; permissive; test-via-API (OpenRouter) → self-host on ≤$5k Linux box. | +| D8 | **`dibbits_workspace` = harvest-then-archive** | Its machinery (crew ops, gates, second-brain) productizes into 4C Shade; repo freezes read-only. | +| D9 | **Entity structure: 4C Digital owns; FutureBuild commercializes** | 4C builds/owns the IP; FutureBuild gets a free perpetual license + is the channel; revenue = license-as-a-service + managed inference. | +| D10 | **Rollout: demo → HH Shade alpha (Dibbits build) → FB Shade → dealers** | De-risk on a throwaway before migrating the live client build. | +| D11 | **Agent skills = quality over quantity** | The 26 crew ops are source material, not a port list. Curate; add incrementally. | +| D12 | **Sequencing: build the customized platform, keep current setup until ready, migrate once** | Avoids a throwaway interim + double migration. | + +## The moat (four-legged flywheel) + +1. **Second brain** — conversations → cited scope/work-items + domain grounding. +2. **QMS-gated, auditable delivery** — controlled-docs + gates-as-objects + full traceability (regulatory tailwind: EU AI Act Aug 2026, ISO 42001). +3. **Owned + vertical + brandable** — self-hosted ` Shade` instances. +4. **Flat economics** — subscription CLI + local OSS Prism; ~nothing metered (SaaS structurally can't copy). + +## The 5 gates + +G-DESIGN (UI/UX approved before build) · G-LOCK (spec → Effective) · G-PUSH (push/deploy) · G-CLIENT (client-visible) · G-MONEY (hours/invoice/payments). + +## Auth / billing rule (load-bearing) + +- **Subscription:** the interactive `claude` CLI in a real terminal, or headless via `CLAUDE_CODE_OAUTH_TOKEN` (draws from subscription limits; watch the `-p` misbilling bug #43333). Rate-limit is the ceiling → subscription-first, API-burst. +- **Metered API:** explicit `ANTHROPIC_API_KEY` / `--bare`, or third-party API-key tools. +- **Gemini/OSS models:** own auth/harness; reached as peers or tools via MCP. + +## Open questions + +**For counsel:** free-perpetual-license scope (does it cover the HH JV?); HH Shade's license path; IP assignment into 4C (incl. Dibbits-engagement work); channel exclusivity (FutureBuild-only vs 4C direct/other channels). + +**Product/technical:** "ready to migrate" = backbone-ready vs full-console-ready; hardware pick (DGX Spark + gpt-oss-120b vs RTX 5090 + Qwen3); demo-project definition; internal-only vs eventual client access. + +**Not yet specced:** crew-ops → skills build spec; GTM / pricing math. diff --git a/docs/4c-shade/LICENSING-AND-ENTITY.md b/docs/4c-shade/LICENSING-AND-ENTITY.md new file mode 100644 index 00000000000..7560c2cc1d1 --- /dev/null +++ b/docs/4c-shade/LICENSING-AND-ENTITY.md @@ -0,0 +1,57 @@ +# 4C Shade — Licensing Framework & Entity / IP Structure + +*Companion to `VISION-BRIEF.md`. Two parts: (A) the permissive-licensing framework that governs component selection, and (B) the entity/IP/commercial structure.* + +--- + +## A · Permissive-licensing framework + +**Core rule:** licensing obligations attach to what you **distribute / fork / host-for-others** — NOT to what you merely **use** to build your own, separately-licensed product. + +Three buckets: + +1. **Dependencies you fork / embed / ship / host-for-dealers** → want most-permissive (MIT/Apache/BSD). Copyleft bites here. **The Shade backbone + custom MCP live here.** +2. **Your own product** (4C Shade, the ShadeOS kit) → your choice; owner-controlled. Goal = **permissive inputs, controlled output.** +3. **Tools you only run** (editor, Claude CLI, terminal, orchestrator) → license ~irrelevant; using GPL/AGPL tools to build never touches your product. + +**Ladder (most → least permissive for a closed commercial product):** MIT/Apache/BSD → MPL/EPL/LGPL (weak, file-level) → GPL (on distribution) → **AGPL (on network use — disqualifying for anything forked/hosted-for-others).** + +### Verdict: keep EPL-Huly + +A more-permissive *and* genuinely-capable backbone does not exist. Every all-in-one alternative is *less* permissive for the fork-and-host model (Plane/Taiga/AppFlowy/Twenty/Docmost/Cal.com = **AGPL**; Outline/NocoDB/Planka/AFFiNE-server = **source-available with host-for-others bars**). The genuinely permissive options (Wekan/Kanboard/Baserow, all MIT) aren't backbones. **Huly's controlled-docs/QMS is ~unique.** EPL fits perfectly: fork + host for dealers = zero disclosure; ship a modified build = release only modified EPL files; proprietary customizations/MCP/config stay yours. + +### Component license map (action items) + +| Component | License | Note for the fork-and-host build | +|---|---|---| +| Huly platform / `@hcengineering/api-client` | **EPL-2.0** | Host for others = no disclosure. Importing api-client does NOT make your MCP EPL. | +| Custom MCP base | prefer **MIT** community servers (`dearlordylord/huly-mcp`, `oculairmedia/huly-mcp-server`) | Avoid the EPL one (`varaprasadreddy9676`) → copyleft-free MCP layer. | +| Infisical | **MIT core** (EE features proprietary) | Self-host core safe; EE = dynamic secrets, approval workflows, SSO-beyond-Google/GitHub. | +| Coordinator model | **gpt-oss (Apache-2.0), Qwen3 (Apache-2.0), GLM-4.5/4.6 (MIT)** | Unconditional — resell inference cleanly. Avoid Gemma/Llama (use-restrictions). | +| Console editor component (if embedded/shipped) | use **Neovim/Lapce (Apache), Ghostty (MIT), tmux (ISC), Terminus (MIT)** | Avoid embedding GPL Zed / AGPL Zed-collab into a *shipped* console. Zed as a *tool you use* is fine. | +| Orchestrators (if embedded/shipped) | **opencode (MIT), Vibe Kanban (Apache)** OK | Claude Squad (AGPL) + Crush (FSL) = use-only; Conductor = proprietary, use-only. | +| SaaS (Stitch, Miro, Workspace, Xero, Mercury, Antigravity) | ToS, not code license | Sharpest: **Xero prohibits training AI/ML on its API data** → design hours→invoice as read-and-act only. | + +--- + +## B · Entity / IP / commercial structure + +**Pattern:** IP-lab + commercial-partner, services-led ("commercial open-source / open-core + services"). + +| Entity | Role | License / revenue | +|---|---|---| +| **4C Digital** (AI/systems R&D lab + dev co) | **Builds + OWNS 4C Shade (the IP)** | Grants FutureBuild a **free perpetual license**; monetizes **license-as-a-service** (customize + implement + maintain) downstream + optional managed-inference tier | +| **FutureBuild** | Commercial / client-facing partner (delivery channel) | Free perpetual Shade license for its own client work | +| **Hardscape House** | Vertical JV (FutureBuild + Dibbits) | Runs **HH Shade** (alpha instance) — license path TBD (via FB's license vs its own from 4C) | +| **Dibbits / dealers / clients** | End customers | Licensed + serviced ` Shade` instances | + +- **Revenue model:** platform **free to the partner (FutureBuild)**; 4C earns from **services** (customization/implementation/maintenance) on end-client deployments + **managed inference**. Not platform-license fees to FB. +- **Reconciles with the framework:** permissive inputs (EPL-Huly + Apache/MIT models) are *why* 4C can own + freely license + resell with no upstream copyleft snag. +- **Branding:** the `Shade` line = "4C Shade by 4C Digital"; FutureBuild = commercial partner; each deployment = ` Shade`. + +### Open items (for Colton + counsel — flags, not decisions) + +1. **Free-perpetual-license scope** — does "FutureBuild's client work" cover the **Hardscape House JV** (separate entity)? Define HH Shade's license path. +2. **License-as-a-service contract** terms (4C-charged vs FB-bundled). +3. **IP assignment** — everything built (incl. during the Dibbits engagement / HH JV) lands in 4C cleanly. +4. **Channel exclusivity** — Shade downstream **only via FutureBuild**, or can 4C also license direct / to other verticals & channels? diff --git a/docs/4c-shade/README.md b/docs/4c-shade/README.md new file mode 100644 index 00000000000..dd4027dd6bd --- /dev/null +++ b/docs/4c-shade/README.md @@ -0,0 +1,19 @@ +# 4C Shade — Product Docs + +This folder captures the **4C Shade** product work. 4C Shade is an **owned, self-hosted, QMS-gated, agent-native software-delivery platform for verticals**, built by **4C Digital**. This repository (`HH Shade`) is the first deployment — the **Hardscape House** instance — currently a repurposed Huly platform fork. + +## Contents + +| Doc | What's in it | +|---|---| +| [`VISION-BRIEF.md`](./VISION-BRIEF.md) | The v1 vision brief — one-liner, positioning, the four-legged-flywheel moat, product contents, architecture, rollout, v1-vs-roadmap, open questions. **Start here.** | +| [`DECISION-LOG.md`](./DECISION-LOG.md) | Condensed record of locked decisions, the moat, the 5 gates, the auth/billing rule, and open questions. | +| [`LICENSING-AND-ENTITY.md`](./LICENSING-AND-ENTITY.md) | The permissive-licensing framework + component license map + the 4C Digital / FutureBuild / Hardscape House entity & IP structure. | + +## Identity stack + +**4C Digital** (owner/lab) · **Shade** (platform) · **4C Shade** (product) · **` Shade`** (FB Shade, HH Shade, Dibbits Shade…) · **Prism** (native OSS coordinator agent) · **ShadeOS** (doctrine/heritage) · **4CDAI** (optional AI-division banner). + +## Status + +Discovery / vision consolidated. This is a **review-and-build draft** — see `VISION-BRIEF.md` §12 for open questions. Instance-specific context for this deployment lives in [`../hh-shade/CONTEXT.md`](../hh-shade/CONTEXT.md); repo-level agent memory is in the root [`CLAUDE.md`](../../CLAUDE.md). diff --git a/docs/4c-shade/VISION-BRIEF.md b/docs/4c-shade/VISION-BRIEF.md new file mode 100644 index 00000000000..f925524debe --- /dev/null +++ b/docs/4c-shade/VISION-BRIEF.md @@ -0,0 +1,93 @@ +# 4C Shade — v1 Vision Brief + +*by 4C Digital · consolidation draft (review-and-build)* + +--- + +## 1 · One-liner + +**4C Shade is an owned, self-hosted, QMS-gated, agent-native software-delivery platform for verticals.** Autonomous agents build the software; every deliverable carries an immutable, auditable **conversation → requirement → spec → code → test → deploy** trail with human sign-off gates as first-class objects. It runs on flat-rate economics (subscription CLI agents + a local OSS coordinator), and each customer gets a branded instance (` Shade`). Built by **4C Digital**, taken to market through **FutureBuild**, first proven on the **HardscapeOS** ERP (HH Shade). + +## 2 · Why now + +- **Origin:** the Dibbits ERP engagement produced the "ShadeOS" command-center (agent crew ops, gates, a conversation-driven second brain). 4C Shade productizes that into an owned delivery OS. +- **Market timing:** generation is solved; **verification / "review debt" is the industry's unsolved bottleneck** (studies show AI ships ~2× the security bugs it fixes). Regulation is arriving — **EU AI Act high-risk enforcement (Aug 2, 2026)** and **ISO 42001** mandate immutable audit logs + "blocking approval gates." 4C Shade's gated, traceable model is early to exactly where the market is being pushed. + +## 3 · Positioning + +**"Autonomous delivery you can prove and stand behind"** — not "delivery, faster." Compete on **provable, accountable, domain-correct** delivery; **ride** the commoditizing agent architecture (Claude/Gemini), **own** the governance + vertical layer. + +## 4 · The moat — a four-legged flywheel + +| Leg | What it is | Why it's defensible | +|---|---|---| +| **Second brain** | Expert conversations (client/prospect calls) → cited scope/work-items/specs + domain grounding for agents | Owns the *upstream* of the loop; compounds with every conversation; extends traceability to origin | +| **QMS-gated delivery** | Controlled-doc specs + 5 gates-as-objects + requirement→…→deploy traceability | Uncontested white space; regulatory tailwind | +| **Owned · vertical · brandable** | Self-hosted per-org ` Shade` instances; domain expertise encoded | Combination uncontested; "vertical *delivery* OS" is empty space | +| **Flat economics** | Subscription CLI agents (Claude Max) + local OSS coordinator (Prism); ~nothing metered | Structurally uncopyable by SaaS (ToS blocks 3rd-party subscription use) | + +**The loop:** conversations → domain knowledge → domain-correct specs → gated autonomous build → traceable delivery → (outcomes + new conversations) → richer knowledge. *Each turn makes the agents more expert and the delivery more provable — on flat cost.* + +## 5 · What's in the product + +- **Backbone (EPL-Huly, self-hosted):** tracker/PM + docs knowledge base + **controlled-documents QMS** (spec lifecycle) + gates-as-objects + multi-workspace. System of record. +- **Console (custom):** agent-native cockpit — fleet view, artifact-first review, and the differentiating surface: **gates + requirement↔spec↔code↔test↔deploy traceability + audit "who-approved-what" ledger + domain-expert sign-off.** +- **Agents:** **Claude CLI** (subscription) for engineering; **Gemini** via MCP for design/planning/multimodal; **Prism** — a local OSS coordinator for always-on PM/scheduling/doc-upkeep. +- **Second brain:** the `intake` / `ingest` / knowledge-graph engine turning conversations into structured, cited work + agent grounding. +- **5 gates:** G-DESIGN, G-LOCK, G-PUSH, G-CLIENT, G-MONEY — human sign-offs as first-class, ISO-42001-aligned objects. +- **Integration (MCP):** GitHub, Infisical (runtime secrets), Stitch + Miro (design / G-DESIGN), Google Workspace/Drive (ingestion + drafts), Xero/Mercury (billing / G-MONEY). + +## 6 · Architecture — two-tier model economy + +- **Prism (local OSS, owned hardware):** always-on coordinator/router — cheap, flat, does run-of-the-mill PM/oversight and (eventually) fronts a single chat UI over the fleet. +- **Claude CLI (subscription):** on-demand heavy engineering, real CLI in a terminal (subscription-billed, not metered). +- **Gemini / product tools (MCP):** design, multimodal, and SaaS tools as needed. +- **Coordination bus = the backbone (Shade/Huly):** agents meet in Shade, not via fragile in-IDE plumbing. +- **Hardware:** a ≤$5k Linux box runs Prism's OSS model — validated via cloud API first, then self-hosted; **doubles as a managed-inference revenue line.** + +## 7 · Entity, IP & commercial model + +- **4C Digital** builds and **owns** 4C Shade (the IP). +- **FutureBuild** = commercial partner: **free perpetual license** for its client-facing work; the delivery channel. +- **Revenue:** **license-as-a-service** (customize + implement + maintain) on downstream ` Shade` deployments + **managed inference**. Platform free to the partner; money in services. +- **Permissive-inputs discipline** (EPL-Huly + Apache/MIT models) is what lets 4C own, license, and resell cleanly. +- **White-label native:** every deployment is ` Shade` — the customer's name is on it. + +*(Detail in `LICENSING-AND-ENTITY.md`.)* + +## 8 · Identity stack + +**4C Digital** (owner) · **Shade** (platform) · **4C Shade** (product / reference build) · **` Shade`** (FB Shade, HH Shade, Dibbits Shade…) · **Prism** (coordinator agent) · **ShadeOS** (doctrine) · **4CDAI** (optional AI-division banner). + +## 9 · Rollout + +1. **Demo project** — prove the flywheel on a small throwaway (de-risk the console). +2. **HH Shade (alpha)** — run the live **Dibbits/HardscapeOS build** on it; the flagship reference instance. +3. **FB Shade** — FutureBuild's branded instance; migrate FutureBuild's projects. +4. **Dealer / other-vertical instances** — the commercial product. + +- **Interim:** keep the current setup (Obsidian + lean-terminal + Plane) until HH Shade is ready; single clean cutover. + +## 10 · v1 scope vs roadmap + +- **v1 (build first):** self-hosted Shade backbone (PM/KB/QMS-specs/gates) + MCP integration + a lean cockpit (Claude CLI + MCP, Zed-hosted) + second-brain intake + the demo project → then the Dibbits migration. **Prism v1 = light** (scheduled routines + doc-upkeep, possibly on a cloud OSS API). +- **Roadmap (not v1):** the forked **custom console** (embedded terminal/browser); **Prism** as full fleet-conduit / single-chat-UI; local self-hosted inference on the $5k box; multi-instance productization + brandable provisioning; the managed-inference offering; commercial GTM to dealers/verticals. + +> **Build guardrail — agent skills = quality over quantity.** Do NOT overbloat the Claude-facing agent tooling. The 26 crew ops are *source material, not a port list* — curate a lean set of high-value skills and add capabilities deliberately/incrementally as each earns its place. + +## 11 · Key decisions locked + +- Backbone = **EPL-Huly self-hosted** (validated as the most-permissive *capable* option). +- Cockpit (interim) = **Claude CLI + MCP, hosted in Zed**; permissive components for anything shipped. +- **Console + backbone both** in scope (console is the product's face); demo-first, single cutover. +- **Most-permissive licensing** driver: permissive inputs, 4C-owned controlled output. +- Model path: **gpt-oss-120b or Qwen3-30B-A3B (Apache-2.0)**, test-via-API → self-host; ≤$5k Linux. +- Old `dibbits_workspace` = **harvest-then-archive** (productized into Shade). + +*(Full decision log in `DECISION-LOG.md`.)* + +## 12 · Open questions to resolve + +- **For counsel:** free-perpetual-license scope (does it cover the HH JV?); HH Shade's license path; **IP assignment** into 4C (incl. Dibbits-engagement work); **channel exclusivity** (FutureBuild-only downstream, or 4C direct / other channels too). +- **Product/technical:** "ready to migrate" = backbone-ready vs full-console-ready; hardware pick (DGX Spark + gpt-oss-120b vs RTX 5090 + Qwen3); the **demo project** definition; internal-only vs eventual client access to instances. +- **Not yet specced:** crew-ops → skills (concrete build requirements for what Shade must implement); GTM / pricing math. diff --git a/docs/hh-shade/CONTEXT.md b/docs/hh-shade/CONTEXT.md new file mode 100644 index 00000000000..6c714cf7247 --- /dev/null +++ b/docs/hh-shade/CONTEXT.md @@ -0,0 +1,37 @@ +# HH Shade — Instance Context + +Instance-specific memory for **HH Shade**, the **Hardscape House** deployment of **4C Shade**. For the product itself, see [`../4c-shade/`](../4c-shade/). + +--- + +## What HH Shade is + +- **The alpha deployment of 4C Shade** — the flagship reference instance that proves the platform. +- **Owner/operator:** the **Hardscape House** joint venture (FutureBuild + Dibbits). License path is an open item (via FutureBuild's perpetual license vs its own from 4C Digital — see `../4c-shade/LICENSING-AND-ENTITY.md`). +- **Current repo state:** an upstream Huly platform fork (EPL-2.0), being repurposed into the Shade backbone. Fork-source archival to an `upstream-mirror` branch is planned but **not yet done**. + +## What it delivers + +HH Shade is the command center for building **HardscapeOS** — a greenfield ERP for hardscape/landscape supply, first client **Dibbits Landscape Supply** (Trenton + Kingston, Ontario). + +## Sibling repositories (the code being delivered) + +- **`dibbits`** — React partner portal + project manual + Phase-1 planning/spec library. Railway auto-deploys `master` → `dibbits.gablelbm.com`. +- **`hardscapeos_dibbits`** — the greenfield HardscapeOS ERP (Go modular monolith backend + Lit frontend). CI + staging deploy to a DigitalOcean droplet (`dibbits-staging.gablelbm.com`). +- *(historical)* **`dibbits_workspace`** — the git+Obsidian "ShadeOS" command-center being **harvested-then-archived**; its machinery (crew ops, gates, second-brain) productizes into 4C Shade. + +## Migration posture + +- **Interim:** work continues on the current setup (Obsidian + lean-terminal + self-hosted Plane at `pm.futurebuild.ai`) until HH Shade is ready. +- **Cutover:** a single clean migration of the live Dibbits build onto HH Shade (no throwaway interim). Open item: define "ready" as **backbone-ready** (sooner) vs **full-console-ready** (later). +- The existing Plane tracker (`DIB` project: 142 issues / 26 cycles / 12 modules) and the `dibbits_workspace` second-brain are the migration source material. + +## v1 scope for this instance + +Shade backbone (PM/KB + controlled-doc QMS specs + gates-as-objects, multi-workspace) + MCP integration + a lean Claude-CLI/Zed cockpit + the second-brain intake engine → then the Dibbits migration. **Prism** (the native OSS coordinator) starts light: scheduled routines + doc-upkeep. Custom console + local self-hosted inference are roadmap, not v1. + +## Key facts + +- **Currency/locale:** CAD, HST 13%, Ontario Construction Act / Bill 60 compliance. +- **Design system (ERP):** "Hardscape Dark" (Stone Amber `#E8A74E`, Deep Earth `#0C0D12`). +- **Money/quantity conventions:** integer cents in app code, `DECIMAL(19,4)` in DB; every quantity paired with a UOM. From 790b55e24f2225009690ca8f76a16caa91e9c0fc Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 16 Jul 2026 00:58:54 +0000 Subject: [PATCH 2/5] docs: add work handoff (console UI/UX prototyping + fork cleanup) for fresh session - docs/4c-shade/HANDOFF.md: self-contained handoff covering Track A (4C Shade console UI/UX map + prototypes, design-first via Stitch/Miro/HTML) and Track B (Huly fork cleanup: baseline=origin/develop, branding + runtime-hide app lean-down) - CLAUDE.md: 'current work' pointer to the handoff Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01Wi5ywDCQ3PytwHmBXdNmhp --- CLAUDE.md | 2 ++ docs/4c-shade/HANDOFF.md | 69 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 docs/4c-shade/HANDOFF.md diff --git a/CLAUDE.md b/CLAUDE.md index 7168522dbb0..f6b43e177c3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,6 +2,8 @@ Guidance for Claude Code sessions working in this repository. +> **▶ CURRENT WORK — start here:** [`docs/4c-shade/HANDOFF.md`](docs/4c-shade/HANDOFF.md). Two active tracks: (A, primary) map + prototype the **4C Shade console UI/UX** (design-first, via Stitch/Miro/local HTML); (B, parallel) **Huly fork cleanup** (baseline + branding + runtime-hide). Read the handoff before starting. + ## What this repo is This is **HH Shade** — the **Hardscape House** deployment of **4C Shade**, an owned, self-hosted, QMS-gated, agent-native software-delivery platform built by **4C Digital**. The repo currently holds an upstream **Huly platform fork** being repurposed into the Shade backbone (alpha). diff --git a/docs/4c-shade/HANDOFF.md b/docs/4c-shade/HANDOFF.md new file mode 100644 index 00000000000..b3ba1d2e830 --- /dev/null +++ b/docs/4c-shade/HANDOFF.md @@ -0,0 +1,69 @@ +# HH Shade — Work Handoff + +*For a fresh Claude Code session scoped to the `hh-shade` repo. Read this + the files it references, then continue the two tracks below. The repo is already renamed to `hh-shade`; develop on branch `claude/dibbits-workspace-consolidation-69sqj8` — **the only branch this environment can push to.*** + +## Read first (context base — already committed in this repo) + +- `CLAUDE.md` — project memory (identity, guardrails, branch). +- `docs/4c-shade/VISION-BRIEF.md` — what 4C Shade is (product, four-legged-flywheel moat, architecture, rollout, v1-vs-roadmap, open questions). **Start here.** +- `docs/4c-shade/DECISION-LOG.md` — locked decisions + open questions. +- `docs/4c-shade/LICENSING-AND-ENTITY.md` — permissive-licensing framework + 4C Digital / FutureBuild / Hardscape House entity & IP structure. +- `docs/hh-shade/CONTEXT.md` — this instance (delivers the Dibbits/HardscapeOS build; sibling repos; alpha status). + +## Working principle — DESIGN-FIRST (the G-DESIGN gate) + +Map and prototype the UI/UX, get it **human-approved**, *then* build. Prototype before implementation. Tools: +- **Stitch** (human-led) — generates screens + a design system; exports tokens / `DESIGN.md` that build agents later consume via its MCP. +- **Miro** (MCP available in-session) — flow maps, architecture/system diagrams, design boards; readable back as reference. +- **Local HTML generation** — fast clickable HTML/CSS prototypes for iteration before any real build. + +--- + +## TRACK A (primary) — 4C Shade console UI/UX map + prototypes + +**Target = the 4C Shade console/platform UI** (product option 1) — the product's own interface. **Spend the design effort on the differentiating surfaces nobody else has; do NOT try to out-polish generic agent-manager UIs (Cursor/GitHub/Antigravity).** + +**Differentiating surfaces to design (the product's face):** +1. **Agent fleet / mission-control view** — see + steer parallel agent threads (Prism coordinator + Claude engineering + Gemini design), grouped by state; artifact-first review (plans, diffs, test evidence). +2. **Gate + traceability cockpit** — the 5 gates (G-DESIGN / G-LOCK / G-PUSH / G-CLIENT / G-MONEY) as first-class objects wired into review; the **requirement ↔ spec ↔ code ↔ test ↔ deploy traceability view**; the audit "who-approved-what" ledger; the **domain-expert sign-off** flow (approve at the spec/gate/artifact level, not only senior-eng diff review). +3. **Second-brain intake view** — expert conversation → cited scope / work-items / specs; the conversation→requirement provenance trail. +4. **Backbone screens it wraps** (mostly Huly's existing UI): tracker (PM), documents (KB), controlled-doc specs (QMS lifecycle). Design the Shade overlays/branding on these. + +**Approach:** +1. Produce a **UI/UX map** — the screen inventory + primary user flows (as a Miro board and/or an outline doc). +2. **Prototype** the priority screens — Stitch for high-fidelity + design system; local HTML for clickable flows. +3. Capture approved designs + tokens (`DESIGN.md`) for the eventual build → the **G-DESIGN** sign-off. + +**Outputs:** `docs/4c-shade/design/` (UI/UX map, wireframe notes, exported tokens) and `prototypes/` (local HTML). This is the **product console**, not the HardscapeOS ERP — keep client-confidential specifics out. + +--- + +## TRACK B (parallel) — Huly fork cleanup + +**Baseline preserved:** the pristine upstream fork is `origin/develop` (`293bc91`) — always diff cleanup against it. (A separate `upstream-mirror` branch was unnecessary and is push-restricted here; `develop` is the baseline.) + +**Chosen approach: baseline + branding + runtime-hide — all reversible; NO build-time stripping this pass.** + +1. **Identity / branding hygiene:** rewrite `README.md` (Huly → HH Shade / 4C Shade); update root `AGENTS.md` / `ARCHITECTURE_OVERVIEW.md` as needed; update `dev/branding.json` (title / name / logo → HH Shade). Remove the upstream "hosted Huly shutting down" notice + Huly marketing. +2. **Runtime app lean-down:** via `dev/branding.json` app preset and/or `models/workbench` `HiddenApplication`, surface only the Shade app set. **Keep all plugins compiled (reversible).** + - **KEEP (Shade spine):** `tracker`, `document`, `controlled-documents`, `test-management`, `activity` (+ `task`, `products`, `questions`, `training`, `survey`). + - **KEEP (framework):** `workbench`, `view`, `text-editor`, `attachment`, `contact`, `setting`, `notification`, `preference`, `tags`, `templates`, `card`, `drive`, `login`/`onboard`/`guest`/`client`. + - **HIDE (other Huly products):** `recruit`, `hr`, `lead`, `board`, `inventory`, `love`, `calendar`, `achievement`, `rating`, `support`, `recorder`, `bitrix`. + - **HIDE (integrations we replace via MCP):** `ai-assistant`, `ai-bot`, `openai`, `gmail`, `telegram`, `mail`, `huly-mail`, `billing`, `payment`, `analytics-collector`. (`chunter`/`chat`, `process` = borderline — hold.) +3. **Defer:** build-time stripping (removing from `models/all/src/index.ts` + `migration.ts`) until the app set is validated running. + +**Verify:** after runtime-hide, the app launcher shows only the Shade set; nothing build-breaking; `git diff origin/develop` is only config/branding. + +**Fork facts (from the audit — don't re-audit):** ~250 MB; ~64 logical apps (each = `x` / `x-assets` / `x-resources` triad → 192 dirs); 22 services; customization levers present (`models/all/src/index.ts`, `models/all/src/migration.ts`, `dev/branding.json`). + +--- + +## Guardrails + +- **Agent skills = quality over quantity** — the 26 ShadeOS crew ops are *source material, not a port list*. Curate; add deliberately. +- **Most-permissive components** for anything forked/embedded/shipped (MIT/Apache; EPL/MPL ok; **avoid AGPL**). Tools you only run are unconstrained. +- **Subscription-first** Claude (official CLI on the subscription); the **5 gates**; branch discipline (push only `claude/dibbits-workspace-consolidation-69sqj8`). + +## Open questions (still pending — see `VISION-BRIEF.md` §12) + +Counsel: license scope / HH path, IP assignment into 4C, channel exclusivity. Technical: "ready to migrate" = backbone-ready vs full-console-ready; hardware pick; the demo-project definition; client-access policy. Unspecced: crew-ops → skills build spec; GTM / pricing. From feb0f65402f4443f9a1c02e24d9b042622b2a8f8 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 16 Jul 2026 02:31:41 +0000 Subject: [PATCH 3/5] branding: rebrand Huly fork to HH Shade + fork-cleanup notes - README/AGENTS/ARCHITECTURE/branding.json rebranded to HH Shade; upstream attribution and build/setup/test docs preserved; hosted-Huly shutdown notice and marketing removed. Branding.json key identifiers left unchanged (title-only). - Track B runtime app-hide investigated and reverted: DISABLED_FEATURES does not hide launcher apps (only Settings->Configuration cards); reverted to baseline auto-translate,mailboxes. Real levers (ExcludedApplications config plumbing, or PluginConfiguration.enabled build-time change) and the true 6-tile scope documented in docs/4c-shade/FORK-CLEANUP-NOTES.md. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01NMd3LatBAyCxj6ZRZuUAha --- AGENTS.md | 2 + ARCHITECTURE_OVERVIEW.md | 6 ++- README.md | 50 +++++------------ dev/branding.json | 12 ++--- dev/prod/public/branding.json | 8 +-- docs/4c-shade/FORK-CLEANUP-NOTES.md | 84 +++++++++++++++++++++++++++++ 6 files changed, 114 insertions(+), 48 deletions(-) create mode 100644 docs/4c-shade/FORK-CLEANUP-NOTES.md diff --git a/AGENTS.md b/AGENTS.md index ac76eb73df6..b8a09b90915 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,6 @@ # Project Instructions +This repository is **HH Shade** — the Hardscape House deployment of **4C Shade**, a fork of the Huly Platform. See [`CLAUDE.md`](CLAUDE.md) for the primary agent guidance and [`docs/4c-shade/`](docs/4c-shade/) for product docs; `CLAUDE.md` takes precedence for Shade work. + - Do not run build commands automatically for verification. - When finishing work, state that the task is complete and ask the user to verify it manually. diff --git a/ARCHITECTURE_OVERVIEW.md b/ARCHITECTURE_OVERVIEW.md index 48b680759ef..e008aa2c39e 100644 --- a/ARCHITECTURE_OVERVIEW.md +++ b/ARCHITECTURE_OVERVIEW.md @@ -1,8 +1,10 @@ -# Huly Platform Architecture Overview +# HH Shade / 4C Shade Architecture Overview + +> HH Shade is a fork of the Huly Platform; this document describes the shared platform backbone that HH Shade / 4C Shade runs on. The service map, ports, and env vars below are the upstream Huly architecture and remain accurate for this fork. ## Service Overview -The Huly platform consists of **30+ microservices** working together in a distributed architecture. Services are organized into functional layers for core business logic, data storage, real-time communication, media processing, and supporting features. +The platform consists of **30+ microservices** working together in a distributed architecture. Services are organized into functional layers for core business logic, data storage, real-time communication, media processing, and supporting features. ### Core Backend Services diff --git a/README.md b/README.md index ac914af7ce8..5faa4113963 100644 --- a/README.md +++ b/README.md @@ -1,51 +1,28 @@ -# Huly Platform +# HH Shade -[![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/huly_io?style=for-the-badge)](https://x.com/huly_io) -![GitHub License](https://img.shields.io/github/license/hcengineering/platform?style=for-the-badge) +**HH Shade** is the Hardscape House deployment of **4C Shade** — a repurposed **Huly platform** fork. See [`docs/4c-shade/`](docs/4c-shade/) for product docs and [`CLAUDE.md`](CLAUDE.md) for agent guidance. -⭐️ Your star shines on us. Star us on GitHub! - -> [!IMPORTANT] -> **Hosted Huly is shutting down — please migrate your data.** -> -> The hosted Huly service is being discontinued because its hosting is no longer being funded. If you keep important data on the hosted platform, export and back it up, and migrate as soon as possible — we can help you move to either a [self-hosted setup](https://github.com/hcengineering/huly-selfhost) or a hosted option. -> -> Not sure how? Follow the [backup & restore guide](docs/guides/backup-restore.en.md) for step-by-step instructions on downloading your backup and restoring it elsewhere. -> -> The service shutdown is expected on **July 20**. Please make sure to export and migrate your data before then rather than wait until the last day. -> -> Have questions or want updates? Join the [Huly community](https://link.huly.io/slack) to discuss migration and stay informed, or email us at [artem@hardcoreeng.com](mailto:artem@hardcoreeng.com) with any questions. This affects only the hosted **Huly** service — self-hosted deployments are not affected. +This repository is a fork of the open-source [Huly Platform](https://github.com/hcengineering/platform) by Hardcore Engineering, being adapted into the Shade backbone. Under the hood it remains the Huly codebase, so the upstream build, setup, and test workflows below still apply to this fork. ## About -The Huly Platform is a robust framework designed to accelerate the development of business applications, such as CRM systems. -This repository includes several applications, such as Chat, Project Management, CRM, HRM, and ATS. -Various teams are building products on top of the Platform, including [Huly](https://huly.io) and [TraceX](https://tracex.co). - -![Huly](https://repository-images.githubusercontent.com/392073243/6d27d5cc-38cd-4d88-affe-bb88b393180c) +The platform is a TypeScript/Svelte framework designed to accelerate the development of business applications (Project Management, CRM, Chat, HRM, ATS, QMS, and more). HH Shade rebrands this framework for the Hardscape House deployment; curating the visible app set down to the Shade spine (tracker, documents, controlled documents, test management, and their supporting framework) is planned but not yet applied — all upstream plugins remain compiled, so nothing is removed. See [`docs/4c-shade/VISION-BRIEF.md`](docs/4c-shade/VISION-BRIEF.md) for what 4C Shade is and [`docs/4c-shade/FORK-CLEANUP-NOTES.md`](docs/4c-shade/FORK-CLEANUP-NOTES.md) for what was changed relative to the upstream fork and what remains deferred. ## Self-Hosting -If you're primarily interested in self-hosting Huly without the intention to modify or contribute to its development, please use [huly-selfhost](https://github.com/hcengineering/huly-selfhost). -This project offers a convenient method to host Huly using `docker`, designed for ease of use and quick setup. Explore this option to effortlessly enjoy Huly on your own server. - -## Activity - -![Alt](https://repobeats.axiom.co/api/embed/c42c99e21691fa60ea61b5cdf11c2e0647621534.svg 'Repobeats analytics image') +This fork is intended to be self-hosted. The upstream project also publishes [huly-selfhost](https://github.com/hcengineering/huly-selfhost), a convenient `docker`-based method to host the vanilla Huly Platform, which is a useful reference for production deployment topology. ## API Client -If you want to interact with Huly programmatically, check out our [API Client](https://github.com/hcengineering/huly.core/tree/main/packages/api-client) documentation. The API client provides a typed interface for all Huly operations and can be used to build integrations and custom applications. - -You can find API usage examples in the [Huly examples](https://github.com/hcengineering/huly-examples) repository. +To interact with the platform programmatically, the upstream [API Client](https://github.com/hcengineering/huly.core/tree/main/packages/api-client) provides a typed interface for platform operations and can be used to build integrations and custom applications. Usage examples live in the upstream [examples](https://github.com/hcengineering/huly-examples) repository. ## Changelog -For detailed information about changes, improvements, and bug fixes in each version, see our [Changelog](./changelog.md). +For detailed information about upstream changes, improvements, and bug fixes in each version, see the [Changelog](./changelog.md). ## Versions -The Huly Platform uses two types of version tags to distinguish between production-ready and development releases: +The upstream platform uses two types of version tags to distinguish between production-ready and development releases: - **Production Versions (`v*`)** - Stable releases for end users - Example: `v0.7.310`, `v0.7.307`, `v0.6.501` @@ -61,14 +38,13 @@ The Huly Platform uses two types of version tags to distinguish between producti ## Architecture -For detailed information about the platform architecture, services, and their interactions, see our [Architecture Overview](./ARCHITECTURE_OVERVIEW.md). +For detailed information about the platform architecture, services, and their interactions, see the [Architecture Overview](./ARCHITECTURE_OVERVIEW.md). ## Table of Contents -- [Huly Platform](#huly-platform) +- [HH Shade](#hh-shade) - [About](#about) - [Self-Hosting](#self-hosting) - - [Activity](#activity) - [API Client](#api-client) - [Changelog](#changelog) - [Versions](#versions) @@ -118,6 +94,8 @@ docker compose version ## Branches & Contributing +This fork develops on feature branches based off `develop` (see [`CLAUDE.md`](CLAUDE.md) for the active branch). The upstream release-flow branches are: + - The `main` branch is the default branch used for production deployments. Changes to this branch are made from the `staging` branch once a version is ready for community use. @@ -126,7 +104,7 @@ docker compose version - The `develop` branch is used for development and is the default branch for contributions. -We periodically merge `develop` into `staging` to perform testing builds. Once we are satisfied with the build quality in our pre-release deployment, we merge changes into `main` and release a new version to the community. +Upstream periodically merges `develop` into `staging` to perform testing builds. Once satisfied with the build quality in pre-release deployment, changes are merged into `main` and a new version is released to the community. ## Setup dev environment @@ -395,4 +373,4 @@ When starting the application (`rush docker:up`), some network ports in Windows 1. Find what's using that port 2. Update the new address in the corresponding service configuration -© 2025 Hardcore Engineering Inc. +HH Shade / 4C Shade is a fork of the Huly Platform. Upstream platform © 2025 Hardcore Engineering Inc. diff --git a/dev/branding.json b/dev/branding.json index 44b2d6d91ed..c0384668fe3 100644 --- a/dev/branding.json +++ b/dev/branding.json @@ -1,40 +1,40 @@ { "huly.local:8080": { "key": "huly-dev", - "title": "Huly", + "title": "HH Shade", "protocol": "http", "language": "en", "lastNameFirst": "true" }, "huly.local:8087": { "key": "huly", - "title": "Huly", + "title": "HH Shade", "protocol": "http", "language": "en", "lastNameFirst": "true" }, "host.docker.internal:8087": { "key": "huly-docker", - "title": "Huly", + "title": "HH Shade", "protocol": "http", "language": "en", "lastNameFirst": "true" }, "huly.local:8081": { "key": "tracex-dev", - "title": "TraceX", + "title": "HH Shade", "protocol": "http", "language": "en" }, "huly.local:8088": { "key": "tracex", - "title": "TraceX", + "title": "HH Shade", "protocol": "http", "language": "en" }, "host.docker.internal:8088": { "key": "tracex-docker", - "title": "Huly", + "title": "HH Shade", "protocol": "http", "language": "en", "lastNameFirst": "true" diff --git a/dev/prod/public/branding.json b/dev/prod/public/branding.json index 530b1ba4ed1..411d27d6e38 100644 --- a/dev/prod/public/branding.json +++ b/dev/prod/public/branding.json @@ -1,6 +1,6 @@ { "huly.local:8080": { - "title": "Huly", + "title": "HH Shade", "languages": "en,ru,pl,pt,pt-br,es,zh,fr,de,ja,ko,tr", "defaultLanguage": "en", "defaultApplication": "tracker", @@ -29,7 +29,7 @@ ] }, "huly.local:8087": { - "title": "Huly", + "title": "HH Shade", "languages": "en,ru,pl,pt,pt-br,es,zh,fr,de,ja,ko,tr", "defaultLanguage": "en", "defaultApplication": "tracker", @@ -58,7 +58,7 @@ ] }, "huly.local:8081": { - "title": "TraceX", + "title": "HH Shade", "languages": "en", "defaultLanguage": "en", "defaultApplication": "documents", @@ -98,7 +98,7 @@ ] }, "huly.local:8088": { - "title": "TraceX", + "title": "HH Shade", "languages": "en", "defaultLanguage": "en", "defaultApplication": "documents", diff --git a/docs/4c-shade/FORK-CLEANUP-NOTES.md b/docs/4c-shade/FORK-CLEANUP-NOTES.md new file mode 100644 index 00000000000..8dca4ac5025 --- /dev/null +++ b/docs/4c-shade/FORK-CLEANUP-NOTES.md @@ -0,0 +1,84 @@ +# HH Shade — Fork Cleanup Notes (Track B) + +*What was changed relative to the pristine upstream fork (`origin/develop` @ `293bc91`), and — importantly — what was investigated and deliberately **not** done. Companion to `HANDOFF.md` "TRACK B". Everything here is reversible; no build-time stripping was performed.* + +--- + +## TL;DR + +- ✅ **Branding hygiene is done** and is the substance of this pass (README, AGENTS, ARCHITECTURE, both `branding.json` files → "HH Shade"; upstream "hosted Huly shutting down" notice + marketing removed; attribution to upstream Huly preserved; build/setup/test docs preserved). +- ↩️ **Runtime app lean-down was attempted via `DISABLED_FEATURES` and reverted** — because a code trace proved `DISABLED_FEATURES` does **not** hide launcher apps. The handoff's suggested Track B mechanism was inaccurate. `DISABLED_FEATURES` is back at its baseline value (`auto-translate,mailboxes`). +- 📌 **Actually hiding the app tiles is deferred** — it requires either a small config-plumbing addition (`ExcludedApplications`) or the model/build-time change the handoff already defers (`PluginConfiguration.enabled=false`). Details below. + +--- + +## 1. What changed (the committed diff vs `origin/develop`) + +| File | Change | +|---|---| +| `README.md` | Rebranded Huly → HH Shade / 4C Shade. Removed the "hosted Huly is shutting down" notice, social/marketing badges, and Repobeats activity image. **Kept** all build/setup/test instructions (they still apply to the fork) and **kept** honest upstream attribution + links. | +| `AGENTS.md` | Added a one-line context note pointing to `CLAUDE.md` / `docs/4c-shade/`. The two behavioral rules ("Do not run build commands…", "When finishing work, state the task is complete…") are **preserved verbatim**. | +| `ARCHITECTURE_OVERVIEW.md` | Title → "HH Shade / 4C Shade Architecture Overview" + a note that the service map is the upstream Huly architecture and remains accurate. Service tables unchanged. | +| `dev/branding.json` | `title` fields "Huly"/"TraceX" → "HH Shade" for the huly/tracex host entries. **`key` identifier fields unchanged** (changing them would break config lookups). | +| `dev/prod/public/branding.json` | Same `title` → "HH Shade" rebrand; `key` fields unchanged. | + +Net diff is **branding + docs only** — no code, model, or migration files touched. + +## 2. The `DISABLED_FEATURES` correction (why the runtime-hide was reverted) + +The handoff proposed hiding non-Shade apps at runtime "via `dev/branding.json` app preset and/or `models/workbench` `HiddenApplication`." A full trace of the front-end showed **all three assumed levers are wrong for a global, all-users, config-only app hide:** + +- **`Branding` type** (`foundations/core/packages/core/src/server.ts`) has only `key/front/title/language/initWorkspace/lastNameFirst/protocol` — **no app field**. `branding.json` can rebrand the title; it cannot hide apps. +- **`workbench.class.HiddenApplication`** is a **per-user `Preference`** (`models/workbench/src/index.ts`) — not a global lever. +- **`DISABLED_FEATURES`** (env → `presentation` metadata `DisabledFeatures` → `isDisabled(feature)`) — despite `docs/disableFeatures.md` saying e.g. "recruit — Will disable Recruit", it does **not** hide any launcher app. It gates exactly four surfaces: the invite UI, account-settings sections (`SettingsCategory.feature`), workspace-settings sections (`WorkspaceSettingCategory.feature`), and **plugin cards in Settings → Configuration** (`Configure.svelte` via `PluginConfiguration.pluginId`). For a token like `recruit`, the only visible effect is hiding the Recruit *card in the admin Configuration grid* — the Recruit app tile in the launcher stays. + +**Proof — the launcher filter never consults `DisabledFeatures`:** + +```ts +// plugins/workbench-resources/src/components/Workbench.svelte:156-164 +const excludedApps = getMetadata(workbench.metadata.ExcludedApplications) ?? [] +const apps = client.getModel() + .findAllSync(workbench.class.Application, { hidden: false, _id: { $nin: excludedApps } }) + .filter((it) => isAllowedToRole(it.accessLevel, account)) +``` + +Apps are filtered by `Application.hidden`, `workbench.metadata.ExcludedApplications`, per-user `HiddenApplication`, and role — never by `DisabledFeatures`. To actually remove a tile you must set `PluginConfiguration.enabled=false` (`models/all/src/index.ts`), which makes `pluginFilterTx` drop the plugin's `Application` create-tx. `DISABLED_FEATURES` never sets `enabled`. + +Because the `DISABLED_FEATURES=…,recruit,lead,inventory,calendar,telegram,github` edit achieved nothing toward the goal (and only hid some admin config cards), it was **reverted** to the baseline `auto-translate,mailboxes` in both resolution points (`dev/docker-compose.yaml`, `dev/prod/public/config.json`). + +*(Doc bugs noted for later: `docs/disableFeatures.md` lists `integration` but the settings category uses `integrations`; `cards` vs plugin id `card`; `training` vs feature `trainings`. Singular/plural mismatches mean those documented tokens silently match nothing.)* + +## 3. Which HIDE-list apps are actually launcher tiles + +Only **6** of the handoff's HIDE list register a top-level `workbench.class.Application` with `hidden: false` (i.e. are shown-by-default tiles): + +| App | Registration | Shown by default | +|---|---|---| +| `recruit` | `models/recruit/src/index.ts` | yes | +| `hr` | `models/hr/src/index.ts` | yes | +| `lead` | `models/lead/src/index.ts` | yes | +| `inventory` | `models/inventory/src/index.ts` | yes | +| `board` | `models/board/src/index.ts` | yes | +| `love` (Office) | `models/love/src/index.ts` | yes | + +The rest of the HIDE list register **no launcher Application** and therefore need no hiding: `calendar` (the tile users see is Time/Planner + Team), `telegram`, `github` (injects a "Pull Requests" special *inside* Tracker), `gmail`, `mail`, `huly-mail`, `billing`, `payment`, `achievement`, `rating`, `support`, `recorder`, `bitrix`, `ai-assistant`, `ai-bot`, `openai`, `analytics-collector`. + +So the real runtime-hide scope is just those **6 tiles**. + +## 4. Recommended next pass — how to actually hide the 6 tiles (choose one) + +**Option A — `ExcludedApplications` config plumbing (reversible, all-users, small code add).** +`Workbench.svelte` already excludes `workbench.metadata.ExcludedApplications`, but **nothing sets it** — only `ExcludedApplicationsForAnonymous` is wired to config (`EXCLUDED_APPLICATIONS_FOR_ANONYMOUS` in `dev/prod/src/platform.ts` + `pods/front/src/__start.ts`). Mirror that wiring: add an `EXCLUDED_APPLICATIONS` config key that `setMetadata(workbench.metadata.ExcludedApplications, [...])` with the Refs of the 6 apps. ~3 small edits (platform.ts, front `__start.ts`, desktop), fully reversible via config, hides tiles for all logged-in users. *Slightly beyond "config-only" (adds plumbing), but no model/migration change.* + +**Option B — `PluginConfiguration.enabled=false` (the handoff's deferred build-time path).** +Set `enabled: false` for the 6 plugins in `models/all/src/index.ts` (+ handle `migration.ts`). This is the upstream-intended way to remove apps and also drops their model txs. It's a model/build-time change → matches the handoff's "Defer: build-time stripping until the app set is validated running." + +**Not recommended:** per-user `HiddenApplication` (not global); `branding.json` (cannot hide apps). + +## 5. Manual verification checklist (no build was run — per project rule) + +- [ ] `git diff origin/develop` shows **only** branding + docs (README, AGENTS, ARCHITECTURE, both branding.json, this notes file) — `DISABLED_FEATURES` back to baseline, no code/model diffs. +- [ ] `dev/branding.json` + `dev/prod/public/branding.json`: `key` fields unchanged; only `title` → "HH Shade". +- [ ] `AGENTS.md` still contains both behavioral rules verbatim. +- [ ] After `rush docker:up` (when you build): app launcher still shows the full Huly set (app-hiding is intentionally deferred — see §4); branding reads "HH Shade". +- [ ] No secrets/tokens introduced. From c6e231224a5f18c9f5f6cdb30859f0ec94cf64c2 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 16 Jul 2026 02:31:50 +0000 Subject: [PATCH 4/5] design: 4C Shade console UI/UX map + prototypes (Track A, G-DESIGN) - docs/4c-shade/design/DESIGN.md - proposed console design system (dark+light tokens, agent identities, component specs for agent-thread card / gate object / traceability node / artifact-review / audit ledger / provenance). - docs/4c-shade/design/UI-UX-MAP.md - 16-screen inventory (P0/P1/P2) + 5 primary user flows with Mermaid diagrams; explicit 'differentiate, do not out-polish' scoping. - prototypes/ - three offline, self-contained clickable prototypes of the differentiating surfaces (agent-fleet mission-control, gate+traceability cockpit, second-brain intake) + index. For human G-DESIGN review. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01NMd3LatBAyCxj6ZRZuUAha --- docs/4c-shade/design/DESIGN.md | 265 ++++++++++++++++++ docs/4c-shade/design/UI-UX-MAP.md | 209 ++++++++++++++ prototypes/agent-fleet.html | 420 ++++++++++++++++++++++++++++ prototypes/gate-traceability.html | 445 ++++++++++++++++++++++++++++++ prototypes/index.html | 211 ++++++++++++++ prototypes/second-brain.html | 317 +++++++++++++++++++++ 6 files changed, 1867 insertions(+) create mode 100644 docs/4c-shade/design/DESIGN.md create mode 100644 docs/4c-shade/design/UI-UX-MAP.md create mode 100644 prototypes/agent-fleet.html create mode 100644 prototypes/gate-traceability.html create mode 100644 prototypes/index.html create mode 100644 prototypes/second-brain.html diff --git a/docs/4c-shade/design/DESIGN.md b/docs/4c-shade/design/DESIGN.md new file mode 100644 index 00000000000..617263b7a18 --- /dev/null +++ b/docs/4c-shade/design/DESIGN.md @@ -0,0 +1,265 @@ +# 4C Shade — Console Design System (`DESIGN.md`) + +*Track A / G-DESIGN deliverable. This is the proposed token set + component spec for the **product console** (not the HardscapeOS ERP — that is "Hardscape Dark", a separate system). Build agents consume this file; the local HTML prototypes in `/prototypes` are its first realization.* + +**Status:** proposal for G-DESIGN sign-off. Nothing here is locked until a human approves the gate. + +--- + +## 1 · Design thesis + +The product is named **Shade** and its positioning is *"autonomous delivery you can prove and stand behind."* The interface is therefore an **instrument, not a hype surface**: calm, dense, evidence-first, and dark-committed. Two subject-native ideas drive the visual language: + +- **Refraction / Prism.** The coordinator agent is *Prism* — it splits one stream of work across a fleet. A single **spectral gradient** (violet → cyan → teal) is the product's one bold motif, reserved for exactly two places: the Prism coordinator and the requirement→…→deploy **traceability spine**. Everywhere else is quiet. +- **Chain-of-custody.** Every traceable object (requirement, spec, commit, test run, gate approval) carries an **ID rendered in monospace**. Monospace is not just for code here — it is the typographic signal of *"this thing has provenance"*. That is the console's typographic character. + +### Scoping rule (load-bearing — repeated from the Track A brief) + +> Spend fidelity on the **differentiating surfaces** (fleet/mission-control, gate + traceability cockpit, second-brain intake). The **backbone screens** (tracker, docs, controlled-doc QMS) are **Huly's existing UI + a Shade overlay** — do *not* redesign them, and do not try to out-polish generic agent-manager UIs (Cursor / GitHub / Antigravity). The tokens below define the *overlay* (top bar, rail, accent, status chips, gate ribbon) that makes a backbone screen read as Shade. + +--- + +## 2 · Color tokens + +Semantic tokens are the contract — components reference these, never raw hex. **Dark is primary** (the name *Shade* commits to it). A full light ramp is specified so build agents can ship a light mode; the prototypes render dark only, by deliberate choice (see §9, open question OQ-1). + +### 2.1 Neutrals — cool blue-slate (chosen, not defaulted) + +The neutral carries a slight blue-cyan hue bias toward the accent, so it reads as selected rather than a generic grey. + +| Token | Dark (primary) | Light | Role | +|---|---|---|---| +| `--bg` | `#0A0D13` | `#F4F7FA` | App canvas (near-black blue-slate) | +| `--surface-1` | `#0F131B` | `#FFFFFF` | Left rail, base panels | +| `--surface-2` | `#151A24` | `#FFFFFF` | Cards, list rows | +| `--surface-3` | `#1C2230` | `#EDF1F6` | Inputs, hover, raised | +| `--surface-4` | `#232B3B` | `#E4EAF2` | Popovers, active row, drawer | +| `--border` | `#242C3A` | `#E2E7EF` | Hairline dividers | +| `--border-2` | `#313B4D` | `#CBD4E1` | Stronger borders, focus outer | +| `--overlay` | `rgba(5,7,11,.62)` | `rgba(30,40,55,.32)` | Scrim behind modals/drawers | + +### 2.2 Ink (text) + +| Token | Dark | Light | Role | +|---|---|---|---| +| `--ink-1` | `#EAEEF6` | `#141922` | Primary text, headings | +| `--ink-2` | `#AEB8CC` | `#47536A` | Secondary text, values | +| `--ink-3` | `#727E93` | `#6C7891` | Muted, captions, labels | +| `--ink-4` | `#4B5567` | `#98A2B4` | Faint, disabled, placeholder | + +### 2.3 Brand accent — "Shade signal" (cyan-teal) + +One accent, used sparingly: primary buttons, focus rings, the active/in-review gate, key links, selection. + +| Token | Dark | Light | +|---|---|---| +| `--accent` | `#37CFBD` | `#12A594` | +| `--accent-hover` | `#4ADED0` | `#159A8B` | +| `--accent-press` | `#28B4A3` | `#0E8577` | +| `--accent-fg` | `#04120F` | `#FFFFFF` | +| `--accent-weak` | `rgba(55,207,189,.14)` | `rgba(18,165,148,.12)` | +| `--accent-line` | `rgba(55,207,189,.38)` | `rgba(18,165,148,.34)` | + +### 2.4 Spectral signature (the one bold motif) + +Reserved for the **Prism coordinator badge** and the **traceability spine rail** only. Never a full-page hero gradient (that is the AI cliché we avoid). + +``` +--spectral: linear-gradient(90deg, #8B7CF0 0%, #4EC5E0 52%, #37CFBD 100%); +--spectral-soft: linear-gradient(90deg, rgba(139,124,240,.16), rgba(78,197,224,.14), rgba(55,207,189,.16)); +``` + +### 2.5 Agent identities + +Each agent chip **always** shows a monogram + name, so color is secondary encoding (colorblind-safe by construction). + +| Token | Dark | Weak tint | Agent | +|---|---|---|---| +| `--prism` | `#8B7CF0` (iris) | `rgba(139,124,240,.14)` | **Prism** — local OSS coordinator | +| `--claude` | `#E0785B` (clay) | `rgba(224,120,91,.14)` | **Claude** — engineering (subscription CLI) | +| `--gemini` | `#5B9DF9` (azure) | `rgba(91,157,249,.14)` | **Gemini** — design / multimodal (MCP) | +| `--human` | `#AEB8CC` (steel) | `rgba(174,184,204,.12)` | **Human** — expert / reviewer / approver | + +Light-mode agent hues: prism `#6D57E0`, claude `#C15A3B`, gemini `#2E6FD6`, human `#5A6478`. + +### 2.6 Status ramp (reserved — never reused as an agent/series color) + +Always paired with an icon **and** a text label; never color-alone. + +| Token | Dark | Weak | Meaning | +|---|---|---|---| +| `--ok` | `#46C98A` | `rgba(70,201,138,.14)` | Passed · approved · effective · green tests | +| `--warn` | `#E7B54B` | `rgba(231,181,75,.14)` | Awaiting sign-off · pending · needs human | +| `--risk` | `#E8894A` | `rgba(232,137,74,.14)` | At-risk · stale · partial | +| `--crit` | `#E86A6A` | `rgba(232,106,106,.14)` | Failed · rejected · blocked | +| `--info` | `#5B9DF9` | `rgba(91,157,249,.14)` | Running · neutral in-progress | + +### 2.7 Gate-state mapping + +| Gate state | Token | Chip | +|---|---|---| +| Approved / passed | `--ok` | ● Passed | +| In review (current focus) | `--accent` | ◆ In review | +| Awaiting human sign-off | `--warn` | ◐ Awaiting | +| Rejected / changes requested | `--crit` | ✕ Rejected | +| Locked / not started | `--ink-3` | ○ Locked | + +--- + +## 3 · Typography + +CSP / offline `file://` constraint: prototypes use the **native system stack** (no webfont fetch, no multi-MB data-URI embeds). Character comes from the scale, weights, spacing, and the monospace-for-identity rule — not from a novelty face. When the real console builds, a licensed grotesque (e.g. a variable sans) may be embedded via `@font-face`; the token names stay. + +```css +--font-sans: ui-sans-serif, system-ui, -apple-system, "Segoe UI Variable Display", + "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; +--font-mono: ui-monospace, "SF Mono", "JetBrains Mono", "Cascadia Code", + "Roboto Mono", Menlo, Consolas, monospace; +``` + +### Type scale + +| Token | Size / line | Weight | Tracking | Use | +|---|---|---|---|---| +| `--fs-display` | 26 / 32 | 600 | -0.01em | Screen title (rare) | +| `--fs-h1` | 20 / 26 | 600 | -0.005em | Panel / section title | +| `--fs-h2` | 16 / 22 | 600 | 0 | Card title, gate name | +| `--fs-h3` | 14 / 20 | 600 | 0 | Sub-head, list group | +| `--fs-body` | 13.5 / 20 | 400 | 0 | Default UI text | +| `--fs-sm` | 12.5 / 18 | 400 | 0 | Secondary / dense | +| `--fs-label` | 11 / 14 | 600 | 0.07em, UPPERCASE | Eyebrows, column heads, chip labels | +| `--fs-mono` | 12.5 / 18 | 450 | 0 | **IDs, hashes, timestamps, code, evidence** | +| `--fs-mono-sm` | 11.5 / 16 | 450 | 0 | Dense mono (ledger, diff gutter) | + +**Rules.** Headings get `text-wrap: balance`. Any column of digits gets `font-variant-numeric: tabular-nums`. Uppercase labels always carry ≥0.07em tracking. Every object ID (`REQ-014`, `G-DESIGN`, `a1b9f3c`, ISO timestamps) is `--font-mono`. + +--- + +## 4 · Spacing, radius, elevation + +```css +/* 4px base spacing scale */ +--sp-1:2px; --sp-2:4px; --sp-3:6px; --sp-4:8px; --sp-5:12px; +--sp-6:16px; --sp-7:20px; --sp-8:24px; --sp-9:32px; --sp-10:40px; --sp-11:48px; + +/* radii */ +--r-1:6px; /* chips, inputs, buttons */ +--r-2:10px; /* cards */ +--r-3:14px; /* panels, drawers */ +--r-pill:999px; + +/* elevation — instrument-grade: prefer surface-step + hairline over heavy shadow */ +--shadow-1: 0 1px 2px rgba(0,0,0,.40); +--shadow-2: 0 8px 28px -10px rgba(0,0,0,.62); +--shadow-pop: 0 16px 48px -14px rgba(0,0,0,.72); + +/* focus ring (accessibility — visible in both themes) */ +--focus: 0 0 0 2px var(--bg), 0 0 0 4px var(--accent); +``` + +Layout uses flex/grid + `gap`, never per-element margins for sibling spacing. Wide content (diffs, tables, the traceability spine) lives in an `overflow-x:auto` container so the page body never scrolls sideways. + +--- + +## 5 · App shell (chrome common to every screen) + +``` +┌──────────────────────────────────────────────────────────────┐ +│ Top context bar · workspace switcher · breadcrumb · gate │ 48px +│ ribbon · global search · actor menu │ +├───────┬──────────────────────────────────────────┬────────────┤ +│ Left │ Main work area │ Inspector │ +│ rail │ (fleet board / gate cockpit / intake) │ drawer │ +│ 60/ │ │ (context, │ +│ 232px │ │ artifact) │ +└───────┴──────────────────────────────────────────┴────────────┘ +``` + +- **Left rail** — collapsible (icon-only 60px ↔ labelled 232px). Groups: **Console** (Fleet, Gates, Second Brain, Activity) above the hairline; **Backbone** (Tracker, Documents, Specs/QMS, Test Mgmt) below — the backbone group is the Huly apps under a Shade overlay. +- **Top context bar** — workspace switcher (` Shade`), breadcrumb, a compact **gate ribbon** (5 gate dots showing global state), search, actor/agent menu. `--surface-1`, hairline bottom border. +- **Inspector drawer** — right, `--surface-1`, opens on selection to show the artifact / provenance / audit context. This is where *artifact-first review* happens. + +--- + +## 6 · Component specs (the differentiating pieces) + +### 6.1 Agent-thread card (`.agent-card`) +The unit of the fleet board. `--surface-2`, `--r-2`, 1px `--border`; left **2px identity stripe** in the agent color. +- **Header:** agent monogram avatar (agent-color weak bg, agent-color ring) · agent name · a monospace **thread id** (`TH-2043`) · a status chip. +- **Body:** the work-item title + linked `REQ`/issue id (mono) · a one-line current-activity string. +- **Artifact row (artifact-first):** up to 3 artifact chips — `◫ Plan`, `⌥ Diff +142/−31`, `✓ Tests 18/18` — each opens that artifact in the inspector. Counts in tabular mono. +- **Footer:** elapsed time · model/tier tag · a "needs review" flag when awaiting a gate. +- **States:** hover raises to `--surface-3`; selected gets `--accent-line` ring + `--accent-weak` wash. + +### 6.2 Fleet column (`.fleet-col`) +Kanban-style column grouped by **thread state**: Planning · Working · Awaiting review · Blocked · Done. Column header = uppercase `--fs-label` + a count. A thread awaiting a human gate shows a `--warn` left edge on its column header. + +### 6.3 Gate object (`.gate`) +A gate is a first-class object, not a checkbox. Card or ribbon-node form. +- **Identity:** gate id in mono (`G-DESIGN`) + human name ("Design approved before build"). +- **State chip** (§2.7) + progress ("3 of 4 items signed"). +- **Required approvers:** stacked actor avatars incl. a **domain-expert** slot (`--human`). +- **Wired to review:** clicking a gate opens the items awaiting it + their traceability + the sign-off action. Gates never auto-pass; a gate stores *who / when / what-hash*. + +### 6.4 Traceability node + edge (`.trace-node`, `.trace-edge`) +The requirement ↔ spec ↔ code ↔ test ↔ deploy spine. +- **Node:** pill with a stage glyph, a stage label (`--fs-label`), and the object id in mono. Node border encodes coverage: solid `--accent-line` = linked & fresh; dashed `--risk` = stale/partial; `--crit` = missing/broken link. +- **Edge:** 2px connector painted with `--spectral` when the whole chain is intact (the one place the spectral motif earns its keep); greyed `--border-2` where the chain is broken. Hovering a node highlights its in/out edges. +- **Node detail:** clicking expands the node inline — source excerpt, author (agent or human), timestamp, content hash — the evidence. + +### 6.5 Artifact-review panel (`.artifact-panel`) — inspector drawer content +Tabbed: **Plan · Diff · Tests · Provenance**. +- **Plan:** rendered markdown of the agent's plan; approve/request-changes footer. +- **Diff:** unified diff, mono, `--ok`/`--crit` gutter tints for +/−, file tree on the left. +- **Tests:** pass/fail summary tiles + a run log; a small pass-rate bar. +- **Provenance:** the mini traceability chain for this artifact + the audit trail of who touched it. +- **Footer action bar:** `Approve` (accent), `Request changes` (ghost, `--crit` text), `Reassign`. Every action writes to the audit ledger. + +### 6.6 Audit-ledger row (`.ledger-row`) +Immutable "who-approved-what". Monospace-forward: `timestamp · actor · action · object-id · content-hash`. Rows are append-only, hash-chained (each row shows a truncated `prev←` hash). Expandable to reveal the full signed payload. Icon + label for the action type; `--ok`/`--crit`/`--warn` accent on the action verb only. + +### 6.7 Provenance / citation card (`.cite-card`) — second brain +Links an extracted work-item back to its origin conversation span. +- **Extracted object:** type badge (Requirement / Work-item / Spec / Risk) + generated id (mono) + one-line statement. +- **Cited source:** a quoted span with speaker + timestamp + source (call / doc), and a **confidence** meter. A "view in conversation" jump scrolls the transcript to the highlighted span. +- **Grounding:** which domain-knowledge nodes this drew on (chips). + +### 6.8 Shared atoms +- **Chip / pill** — `--r-pill`, `--fs-label`, weak-tint bg + full-color text/glyph. Variants: status, agent, gate-state, artifact. +- **Button** — primary (accent bg, `--accent-fg`), ghost (transparent, `--border` ring), danger-ghost (`--crit` text). 32px default height, `--r-1`, `--fs-body` 600. +- **Stat tile** — big tabular number + `--fs-label` caption + optional inline sparkline; used in the fleet summary strip. +- **Meter / bar** — 6px track `--surface-3`, fill in status or accent; pass-rate, confidence, gate progress. + +--- + +## 7 · Data-visualization rules (from the `dataviz` method) + +- **One axis, ever.** No dual-scale charts. +- **Categorical = fixed agent order** (Prism, Claude, Gemini, Human) — never cycled; a colored mark always sits beside a text label. +- **Sequential** (e.g. coverage heat): single hue, light→dark off the accent ramp. +- **Status colors are reserved** (§2.6) and never used as a data series. +- Charts stay small and inline (fleet throughput sparkline, pass-rate bar, gate-progress meter). Grid/axes recessive; endpoints emphasized; text wears ink tokens, not the series color. + +--- + +## 8 · Accessibility & motion + +- Contrast: body text ≥ 4.5:1 on its surface; large text/labels ≥ 3:1. Accent text (`--accent-fg` on `--accent`) verified for buttons. +- Never color-alone: status, agent, and gate identity always carry an icon/monogram + label. +- Visible keyboard focus (`--focus`) on every interactive element. +- Respect `prefers-reduced-motion`: no non-essential transitions; the spectral motif is static (no animated gradient) under reduced-motion. +- Motion budget is tiny by design — hover elevation, drawer slide, expand/collapse. No ambient animation (this is an instrument). + +--- + +## 9 · Open design questions for G-DESIGN + +- **OQ-1 — Light mode in v1?** The prototypes commit to dark (the *Shade* thesis). Tokens support light. Decide: dark-only v1, or ship both? (Recommendation: dark-primary, light as fast-follow.) +- **OQ-2 — Rail scope.** How many backbone apps surface in the rail by default vs. under a "more" affordance? (Ties to the Track-B lean-down set.) +- **OQ-3 — Single-chat-over-fleet (Prism front).** Roadmap says Prism eventually fronts one chat UI over the whole fleet. Do we design that conversational surface now, or keep the board-first model for v1? +- **OQ-4 — Gate rigidity.** Are all 5 gates mandatory per work-item, or configurable per workspace/project? Affects whether the gate ribbon is fixed or authored. +- **OQ-5 — Embedded font.** Ship a licensed variable grotesque via `@font-face` for the real build, or stay on the native stack? (Prototypes stay native for offline fidelity.) + +--- + +*Token source of truth for the prototypes: this file. If a prototype and this file disagree, this file wins and the prototype is the bug.* diff --git a/docs/4c-shade/design/UI-UX-MAP.md b/docs/4c-shade/design/UI-UX-MAP.md new file mode 100644 index 00000000000..862dcd4ed85 --- /dev/null +++ b/docs/4c-shade/design/UI-UX-MAP.md @@ -0,0 +1,209 @@ +# 4C Shade — Console UI/UX Map (`UI-UX-MAP.md`) + +*Track A / G-DESIGN deliverable. Screen inventory + primary user flows for the **product console** (the 4C Shade / ` Shade` interface). Companion to `DESIGN.md` (tokens) and the clickable prototypes in `/prototypes`. Keeps client-confidential HardscapeOS/Dibbits specifics out — examples are generic software-delivery.* + +--- + +## 1 · Design principles + +1. **Agent-native, not human-CRUD.** The primary operators are agents (Prism / Claude / Gemini); the human's job is to **steer and sign off**, not to type every field. The default view is a *fleet of work in motion*, not an empty form. +2. **Artifact-first review.** You review the **thing produced** — a plan, a diff, test evidence, a spec — not a status label about it. Every state in the console is one click from the artifact that justifies it. +3. **Gates & traceability are first-class objects.** The 5 gates and the requirement→spec→code→test→deploy chain are navigable objects with their own state, approvers, and audit history — not metadata hidden in a sidebar. This is the moat surface; it gets the fidelity. +4. **Provable delivery over faster delivery.** When "show more evidence" competes with "fewer clicks", evidence wins. Immutable audit, content hashes, and who-approved-what are visible by default because the product's promise is *"delivery you can stand behind."* +5. **Provenance runs to the origin.** Nothing is a floating assertion: a work-item traces up to the **conversation span** that created it (second brain) and down to the **deploy** that satisfied it. The chain is the product. +6. **Scoping discipline — differentiate, don't out-polish.** High fidelity goes to the surfaces **nobody else has**: fleet/mission-control, the gate + traceability cockpit, and second-brain intake. The **backbone screens** (tracker, docs, controlled-doc QMS) are **Huly's existing UI + a Shade overlay** (top bar, rail, accent, gate ribbon, status chips) — we do **not** redesign them and we do **not** try to beat Cursor / GitHub / Antigravity at generic agent-manager UX. + +--- + +## 2 · Screen inventory + +Priority: **P0** = differentiating (build & prototype first) · **P1** = supporting console · **P2** = backbone overlay (Huly UI + Shade skin, minimal net-new design). + +| # | Screen | Purpose | Priority | Primary artifacts shown | +|---|---|---|---|---| +| S1 | **Fleet / Mission Control** | See + steer all parallel agent threads, grouped by state | **P0** | Agent-thread cards; plan / diff / test-evidence chips; fleet summary tiles | +| S2 | **Agent Thread detail** | Drill into one agent's run: transcript, plan, artifacts, hand-offs | **P0** | Plan doc, unified diff, test run log, tool calls, provenance chain | +| S3 | **Gate Cockpit** | The 5 gates as objects; queue of items awaiting each gate | **P0** | Gate objects; items-awaiting list; approver roster | +| S4 | **Traceability view** | requirement ↔ spec ↔ code ↔ test ↔ deploy spine for a work-item | **P0** | Trace nodes/edges; per-node evidence; coverage state | +| S5 | **Audit Ledger** | Immutable who-approved-what, hash-chained | **P0** | Ledger rows (actor · action · object · hash · time) | +| S6 | **Domain-expert sign-off** | Approve at spec/gate/artifact level (not only eng diff review) | **P0** | Spec/artifact under review; sign-off action; expert notes | +| S7 | **Second-Brain Intake** | Expert conversation → cited scope / work-items / specs | **P0** | Transcript with highlighted spans; extracted item cards; citations | +| S8 | **Knowledge Graph** | Browse domain-knowledge nodes agents are grounded on | P1 | Concept nodes, sources, links to specs/items | +| S9 | **Artifact Review drawer** | Shared inspector: Plan / Diff / Tests / Provenance tabs | **P0** | Whatever artifact is selected, + its audit + trace | +| S10 | **Global search / command** | Jump to any object by id (REQ-, G-, TH-, hash) | P1 | Ranked objects across all types | +| S11 | **Workspace / instance switch** | Switch ` Shade` workspace + settings | P1 | Workspace list, members, agent roster, gate config | +| S12 | **Activity feed** | Chronological cross-object event stream | P1 | Activity items (Huly `activity` overlay) | +| S13 | **Tracker (PM)** | Issues / cycles / modules | **P2** | Huly tracker + Shade overlay | +| S14 | **Documents (KB)** | Knowledge base docs | **P2** | Huly documents + Shade overlay | +| S15 | **Controlled Docs (QMS specs)** | Spec lifecycle Draft→Review→Effective | **P2** | Huly controlled-documents + Shade overlay + gate wiring | +| S16 | **Test Management** | Test suites / runs | **P2** | Huly test-management + Shade overlay | + +**Prototyped this pass (highest-value P0):** S1 (`agent-fleet.html`), S3+S4+S5+S6 combined (`gate-traceability.html`), S7 (`second-brain.html`). S2 and S9 appear as the inspector drawer inside those. + +--- + +## 3 · The 4 differentiating surfaces (prototype-grade detail) + +### Surface A — Agent fleet / mission control (S1, S2, S9) + +**Goal:** one screen to see everything the fleet is doing and to intervene, review, or approve — artifact-first. + +- **Fleet summary strip** (top): stat tiles — *Active threads · Awaiting your review · Blocked · Merged today* — plus a tiny throughput sparkline (threads reaching "Done" over the last N hours). Reserved status colors; tabular numerics. +- **Board:** columns by **thread state** — Planning · Working · Awaiting review · Blocked · Done. Each column header shows a count; an "Awaiting review" column carries a `--warn` edge because it is the human's queue. +- **Agent-thread card** (§6.1 of DESIGN.md): identity stripe in agent color, monogram avatar, thread id (mono), work-item + `REQ` link, one-line current activity, **artifact chips** (`Plan`, `Diff +142/−31`, `Tests 18/18`), elapsed time, model/tier tag. A card awaiting a gate shows a gate badge. +- **Steer actions on a card:** Approve plan · Request changes · Reassign (Prism↔Claude↔Gemini) · Pause · Open thread. Selecting a card opens the **inspector drawer** (S9) with Plan / Diff / Tests / Provenance tabs. +- **Grouping toggle:** by state (default) · by agent · by work-item / epic · by gate. +- **Why it differentiates:** it is *fleet* mission-control (many parallel threads across three agent types) with **review built into the card**, not a single-agent chat log. The artifact-first chip row is the wedge. + +### Surface B — Gate + traceability cockpit (S3, S4, S5, S6) + +**Goal:** make the QMS-gated, fully-traceable delivery loop *operable* — the uncontested white space. + +- **Gate ribbon / board:** the 5 gates — **G-DESIGN · G-LOCK · G-PUSH · G-CLIENT · G-MONEY** — as objects, each with state chip, progress ("3 of 4 signed"), and required approvers (including a **domain-expert** slot). Selecting a gate reveals its **queue of items awaiting sign-off**. +- **Traceability spine (S4):** for a selected work-item, a horizontal **requirement → spec → code → test → deploy** chain of nodes; edges painted with the spectral gradient when the chain is intact, greyed/dashed where a link is stale or missing. Each node expands to its **evidence** (source excerpt, author agent/human, timestamp, content hash). This is the "prove it" view. +- **Audit ledger (S5):** append-only, hash-chained rows — `timestamp · actor · action · object-id · hash (prev←)`. Filterable by gate, actor, object. Immutable by design (ISO-42001-aligned). +- **Domain-expert sign-off (S6):** the differentiator vs. senior-eng-only review — an expert approves at the **spec / gate / artifact** level. Action panel: view the spec + its traceability, add expert notes, then **Sign off** (writes actor + hash + time to the ledger) or **Request changes**. Approvals are scoped: an expert can sign G-DESIGN or a spec's correctness without touching code review. +- **Why it differentiates:** gates-as-objects + full requirement↔deploy traceability + an immutable audit ledger + non-engineer expert sign-off is the combination competitors don't have and regulation (EU AI Act Aug 2026, ISO 42001) is about to demand. + +### Surface C — Second-brain intake (S7, S8) + +**Goal:** turn expert conversations into cited, grounded, structured work — owning the *upstream* of the flywheel. + +- **Three panes:** (1) **conversation transcript** with speaker turns + timestamps and **highlighted spans** where intake extracted something; (2) **extracted items** — cards typed as Requirement / Work-item / Spec / Risk, each with a generated id (mono), a one-line statement, and a **confidence** meter; (3) **provenance** — clicking an item jumps the transcript to and highlights the exact span that produced it, showing speaker + timestamp + source. +- **Grounding:** each item shows which **domain-knowledge nodes** it drew on / contributes to (chips linking to S8). Accept / edit / reject controls promote an extracted item into the tracker or the spec library — carrying its citation with it. +- **Provenance trail:** the promoted work-item keeps a permanent **conversation → requirement** link, so the traceability spine (Surface B) can run all the way back to the sentence a domain expert actually said. +- **Why it differentiates:** competitors start at "here's a ticket." Shade starts at "here's the conversation, and here's the cited line that justifies this requirement" — and that citation survives all the way to deploy. + +### Surface D — Backbone screens with Shade overlays (S13–S16) — **P2, do not redesign** + +**Goal:** make Huly's tracker / documents / controlled-docs / test-management read as one product with the console, with *minimum* net-new design. + +- **The overlay = tokens only:** apply the Shade top context bar, left rail, accent, status/gate chips, and the gate ribbon to Huly's existing screens. Rebrand (` Shade`), swap the palette to the Shade tokens, and wire the **controlled-documents lifecycle** (Draft → In review → **Effective**) to **G-LOCK** so a spec going Effective is a real gate event that lands in the audit ledger. +- **Explicitly out of scope this pass:** re-laying-out tracker boards, doc editors, or test grids. Those are Huly's, and they are good enough; our fidelity budget is spent on Surfaces A–C. + +--- + +## 4 · Primary user flows + +### Flow 1 — Steer a parallel agent fleet + review an artifact + +1. Operator opens **Fleet / Mission Control (S1)**; scans the summary strip — *2 threads awaiting review*. +2. Filters/groups the board by **Awaiting review**; sees a Claude thread `TH-2043` on `REQ-014` with a `Diff +142/−31` and `Tests 18/18` chip. +3. Clicks the card → **inspector drawer (S9)** opens on the **Diff** tab; flips to **Tests** (all green) and **Provenance** (chain intact back to `REQ-014`). +4. Approves the plan / diff → action writes to the **audit ledger (S5)**; thread advances toward its next gate. +5. A Gemini design thread is stuck in **Blocked** → operator **reassigns** part of the work to Prism to unblock, or opens the thread (S2) to add direction. + +```mermaid +flowchart LR + A[Open Fleet S1] --> B{Anything awaiting review?} + B -- yes --> C[Group by Awaiting review] + C --> D[Select thread card TH-2043] + D --> E[Inspector: Plan / Diff / Tests / Provenance] + E --> F{Evidence sufficient?} + F -- approve --> G[Approve -> writes audit ledger] + F -- no --> H[Request changes -> back to agent] + B -- blocked exists --> I[Open blocked thread] + I --> J[Reassign Prism/Claude/Gemini or steer] + G --> K[Thread advances to next gate] +``` + +### Flow 2 — Gate approval (G-DESIGN) with the traceability view + +1. Operator opens **Gate Cockpit (S3)**; the gate ribbon shows **G-DESIGN** with `◐ Awaiting · 3 of 4 signed`. +2. Selects **G-DESIGN** → queue of items awaiting design sign-off; picks work-item `WI-88 "Checkout redesign"`. +3. Opens its **traceability spine (S4)**: `REQ-014 → SPEC-07 → (code pending) → (tests pending) → (deploy pending)`; the requirement→spec edge is intact (spectral), later edges are locked because the gate hasn't passed. +4. Reviews the **spec artifact** + expands each node's evidence (who authored, when, hash). +5. Confirms required approvers; the **domain-expert** slot is still open → routes to the expert (Flow 3) or, if the operator *is* the last approver, **signs off**. +6. Sign-off writes actor + object + content-hash + timestamp to the **audit ledger (S5)**; G-DESIGN flips to `● Passed`; downstream gates (G-LOCK…) unlock; the spectral chain extends. + +```mermaid +flowchart TD + A[Gate Cockpit S3] --> B[Select G-DESIGN] + B --> C[Queue of items awaiting sign-off] + C --> D[Pick WI-88] + D --> E[Traceability spine S4] + E --> F[Expand node evidence: author, time, hash] + F --> G{All required approvers signed?} + G -- expert slot open --> H[Route to domain expert - Flow 3] + G -- operator is last --> I[Sign off] + H --> I + I --> J[Append to audit ledger S5 with hash] + J --> K[G-DESIGN = Passed -> unlock G-LOCK] +``` + +### Flow 3 — Domain-expert sign-off at spec / gate level + +1. Domain expert (not an engineer) receives a review request; opens **Domain-expert sign-off (S6)** for `SPEC-07`. +2. Sees the spec, its **traceability** to `REQ-014`, and the **cited conversation origin** (link into S7) — no code required to judge correctness. +3. Reads the requirement's provenance; confirms the spec is domain-correct; adds expert notes. +4. **Signs off** (scoped to spec correctness / G-DESIGN) → recorded in the **audit ledger (S5)** with the expert as actor. Or **Requests changes**, which returns the item to the responsible agent thread (S2) with the notes attached. +5. The gate's approver roster updates; when the last required approver signs, the gate passes (rejoins Flow 2 step 6). + +```mermaid +flowchart LR + A[Review request] --> B[Domain-expert sign-off S6] + B --> C[Spec + traceability + cited origin] + C --> D{Domain-correct?} + D -- yes --> E[Add notes + Sign off scoped] + D -- no --> F[Request changes -> agent thread S2] + E --> G[Audit ledger records expert + hash] + F --> H[Agent revises -> re-review] + G --> I[Approver roster updates -> gate may pass] +``` + +### Flow 4 — Second-brain intake: conversation → cited scope / work-items + +1. A client/prospect call transcript lands in **Second-Brain Intake (S7)** (via Google Drive/Workspace MCP or manual paste). +2. Intake highlights spans and proposes **extracted items** (Requirement / Work-item / Spec / Risk), each with a confidence meter. +3. Operator clicks an extracted `REQ-014` → transcript scrolls to and highlights the **exact span** the expert said; provenance shows speaker + timestamp + source. +4. Operator **accepts / edits / rejects** each item; accepted items promote into the **tracker / spec library**, carrying the citation. +5. The promoted item now has a permanent **conversation → requirement** link, so Surface B's traceability spine can run from the spoken sentence all the way to deploy. + +```mermaid +flowchart TD + A[Transcript ingested - Drive MCP / paste] --> B[Intake extracts + highlights spans] + B --> C[Extracted item cards + confidence] + C --> D[Operator selects REQ-014] + D --> E[Transcript jumps to cited span + speaker/time] + E --> F{Accept / edit / reject} + F -- accept --> G[Promote to tracker / spec library WITH citation] + F -- edit --> G + F -- reject --> H[Discard - logged] + G --> I[Permanent conversation->requirement link] + I --> J[Feeds Surface B traceability to deploy] +``` + +### Flow 5 — Spec lifecycle → G-LOCK (backbone overlay in action) + +1. In **Controlled Docs (S15, Huly + overlay)** a spec sits in **In review**. +2. Reviewers (incl. domain expert via S6) approve; the spec is set **Effective**. +3. Going Effective **fires G-LOCK** — a real gate event written to the audit ledger; the spec version is frozen and its hash recorded. +4. The traceability spine (S4) marks the `spec` node as locked/fresh; downstream code work may now start against a frozen spec. + +```mermaid +flowchart LR + A[Spec In review - S15 overlay] --> B[Reviewers + expert approve] + B --> C[Set Effective] + C --> D[Fires G-LOCK gate event] + D --> E[Ledger records version + hash - immutable] + E --> F[Trace node 'spec' = locked/fresh] + F --> G[Code work unlocked against frozen spec] +``` + +--- + +## 5 · Navigation model + +- **Left rail** — *Console* group (Fleet · Gates · Second Brain · Activity) over the hairline; *Backbone* group (Tracker · Documents · Specs/QMS · Tests) under it. Collapsible to icons. +- **Top context bar** — ` Shade` workspace switcher · breadcrumb · **gate ribbon** (5 dots, global gate state, always visible) · global search (`⌘K`, jump by object id) · actor/agent menu. +- **Inspector drawer** — right, opens on any object selection; the single home of artifact-first review across screens. +- **Cross-links are the point:** a thread card → its work-item → its traceability spine → each node's evidence → the gate it's blocked on → the ledger row that will record the approval → back to the conversation span that started it. Every arrow in the flywheel is a clickable link in the UI. + +--- + +## 6 · What we deliberately did NOT design + +- Tracker boards, doc editor, test grids — **Huly's**, kept as-is under the overlay. +- A bespoke terminal/browser-embedded console — **roadmap**, not v1 (interim cockpit is Claude CLI + MCP in Zed). +- Prism's single-chat-over-fleet conversational surface — flagged **OQ-3** for G-DESIGN; board-first for v1. +- Billing/invoice screens for G-MONEY beyond the gate object itself — deferred to the Xero/Mercury MCP integration pass. diff --git a/prototypes/agent-fleet.html b/prototypes/agent-fleet.html new file mode 100644 index 00000000000..05e7e0e7343 --- /dev/null +++ b/prototypes/agent-fleet.html @@ -0,0 +1,420 @@ + + + + + +Fleet · Mission Control — 4C Shade + + + +
+ +
+
Shade
+
Acme Shade ▾
+
Console / Fleet · Mission Control
+
+
+ G-DESIGN + G-LOCK + G-PUSH + G-CLIENT + G-MONEY +
+
⌕ Search objects… ⌘K
+
CT
+
+ +
+ + + + +
+
+
Active threads
14
3 Prism · 8 Claude · 3 Gemini
+
Awaiting your review
2
gate sign-off queue
+
Blocked
1
CI failure · TH-2051
+
Merged today
9
+3 vs. yesterday
+
+
Throughput · 12h
+ + + + + + +
threads reaching Done / hour
+
+
+ +
+ Group by +
+ +
+ All agents ▾ + Workspace: Acme ▾ +
+ Live · updated 4s ago +
+ +
+ +
+
+ + + +
+
+ + + + diff --git a/prototypes/gate-traceability.html b/prototypes/gate-traceability.html new file mode 100644 index 00000000000..dc74868a103 --- /dev/null +++ b/prototypes/gate-traceability.html @@ -0,0 +1,445 @@ + + + + + +Gates · Traceability Cockpit — 4C Shade + + + +
+
+
Shade
+
Acme Shade ▾
+
Console / Gates · Traceability Cockpit
+
+
⌕ Search objects… ⌘K
+
CT
+
+ +
+ + +
+

Gates & Traceability

+
The 5 delivery gates as first-class objects · requirement → spec → code → test → deploy · immutable audit ledger.
+ +
+ +
+ +
+
Awaiting G-DESIGN3 items
+
+
+ + +
+
+ WI-88 + — + ◆ In G-DESIGN +
+
+
Traceability spinecoverage 2 / 5
+
+
+ +
Audit ledger · append-only, hash-chained
+
+
timestamp
actor
action · object
hash
+
+
+
+
+ + + +
+
+
+
+ + + + diff --git a/prototypes/index.html b/prototypes/index.html new file mode 100644 index 00000000000..1df68c50729 --- /dev/null +++ b/prototypes/index.html @@ -0,0 +1,211 @@ + + + + + +4C Shade Console — G-DESIGN Prototypes + + + +
+
+ +

4C SHADE · Console

+ G-DESIGN · design pass · Track A +
+ +
+

Autonomous delivery you can prove and stand behind.

+

The console is an instrument, not a hype surface: agent-native, artifact-first, with gates and full requirement→deploy traceability as first-class objects. These three clickable mockups prototype the differentiating surfaces — the ones no generic agent-manager (Cursor / GitHub / Antigravity) has. Backbone screens (tracker / docs / QMS) stay Huly's UI under a Shade overlay and are deliberately not redesigned.

+
+ agents · Prism ● · Claude ● · Gemini ● + gates · G-DESIGN · G-LOCK · G-PUSH · G-CLIENT · G-MONEY + offline · opens via file:// · no network +
+
+ +
Prototyped surfaces · click to open
+
+ + +
01 +
+
+
+
+
+
+
+
mission-controlartifact-first
+

Agent Fleet

+

See and steer every parallel agent thread grouped by state; review the plan, diff and test evidence right on the card.

+ Open prototype → +
+ + + +
02 +
+
REQ
+
SPEC
+
CODE
+
TEST
+
+
+
+
gates-as-objectsaudit ledger
+

Gate & Traceability Cockpit

+

The 5 gates as objects, the requirement↔spec↔code↔test↔deploy spine, an immutable who-approved-what ledger, and a live domain-expert sign-off.

+ Open prototype → +
+ + + +
03 +
+
+
+
+
+
+
conversation→specprovenance
+

Second-Brain Intake

+

Expert conversation → cited requirements, work-items and specs, each traceable back to the exact spoken span that created it.

+ Open prototype → +
+ +
+ +
Design system & scope
+
+
+

One system · dark-committed "Shade"

+

All three prototypes are driven by the same token set — cool blue-slate ground, one luminous cyan-teal accent, and a single spectral motif (violet→cyan→teal) reserved for the Prism coordinator and the traceability spine. Monospace carries every traceable ID (chain-of-custody as typography).

+
+ accent + Prism + Claude + Gemini + pass + awaiting + blocked +
+
◫ tokens & component specs · docs/4c-shade/design/DESIGN.md↗
+
◫ screen inventory & flows · docs/4c-shade/design/UI-UX-MAP.md↗
+
+
+

Backbone = Huly UI + Shade overlay (not redesigned)

+

Tracker, Documents, Controlled-doc QMS specs and Test Management keep Huly's existing screens. The Shade "overlay" is tokens only — top bar, rail, accent, status/gate chips — plus wiring the spec lifecycle (Draft→Effective) to G-LOCK.

+

Open questions for the gate

+
    +
  • OQ-1 Ship a light mode in v1, or commit fully to dark?
    • +
  • OQ-3 Design Prism's single-chat-over-fleet now, or keep board-first for v1?
    • +
  • OQ-4 Are all 5 gates mandatory per item, or configurable per workspace?
    • +
+
+
+ +
+ 4C Shade · product console · design-first / G-DESIGN + placeholder data — generic software-delivery, no client specifics +
+
+ + diff --git a/prototypes/second-brain.html b/prototypes/second-brain.html new file mode 100644 index 00000000000..0d23bd5091e --- /dev/null +++ b/prototypes/second-brain.html @@ -0,0 +1,317 @@ + + + + + +Second Brain · Intake — 4C Shade + + + +
+
+
Shade
+
Acme Shade ▾
+
Console / Second Brain · Intake
+
+
⌕ Search objects… ⌘K
+
CT
+
+ +
+ + +
+ +
+
+

Discovery call — Checkout & billing scope

+
+ ▶ Call transcript + ◫ ingested via Google Drive MCP + 2026-06-12 · 41 min · 2 participants + 6 items extracted by Prism +
+
+
+
+ DO +
Dana · ops lead (client) 14:21:40
+

So the biggest thing for us on checkout — the order total has to be exact to the cent. No rounding surprises when the customer gets to the till. We've been burned by that before with floating-point math.

+
+
+ SA +
Sam · delivery analyst 14:22:10
+

Understood — we'll model money as integer cents end-to-end. What about payment retries?

+
+
+ DO +
Dana · ops lead (client) 14:23:02
+

Right — a payment must be safe to retry. If the network hiccups and the request goes twice, the customer must never be double-charged. That's non-negotiable.

+
+
+ DO +
Dana · ops lead (client) 14:25:30
+

Also the current flow is three separate pages and people drop off. Ideally checkout collapses into one page you can review before paying.

+
+
+ SA +
Sam · delivery analyst 14:27:05
+

Good. On the finance side — anything the invoice must show?

+
+
+ DO +
Dana · ops lead (client) 14:27:48
+

Yes — every invoice needs the tax broken out as its own line and it has to reference the purchase-order number. Finance reconciles against the PO.

+
+
+ DO +
Dana · ops lead (client) 14:33:12
+

Oh — and one warning. Last quarter our public search endpoint got hammered by a bot and it took the whole portal down. There's no rate limit on it today. Whatever you build, don't repeat that.

+
+
+ DO +
Dana · ops lead (client) 14:38:55
+

Down the road we might want to export everything to our accounting system, but honestly that's a maybe — don't hold up phase one for it.

+
+
+
+ + +
+
+

Extracted items

6 cited
+
+ + + + + +
+
+
+
+
+
+
+ + + + From 300f29fe035c5ee58d2a3d84e1a32cccf427b36c Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 16 Jul 2026 02:42:39 +0000 Subject: [PATCH 5/5] docs: correct FORK-CLEANUP-NOTES app-hide scope (3 tiles, not 6) Source-verified against models/all/src/index.ts: only recruit/hr/love are shown-by-default launcher tiles (Application.hidden:false AND PluginConfiguration.enabled:true). lead/inventory/board register apps but are enabled:false (already pruned by pluginFilterTx); the rest register no launcher app. Corrects an earlier draft that listed 6 shown tiles. Next-pass options updated to the 3-app scope. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01NMd3LatBAyCxj6ZRZuUAha --- docs/4c-shade/FORK-CLEANUP-NOTES.md | 30 ++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/4c-shade/FORK-CLEANUP-NOTES.md b/docs/4c-shade/FORK-CLEANUP-NOTES.md index 8dca4ac5025..cd6170fad79 100644 --- a/docs/4c-shade/FORK-CLEANUP-NOTES.md +++ b/docs/4c-shade/FORK-CLEANUP-NOTES.md @@ -48,30 +48,30 @@ Because the `DISABLED_FEATURES=…,recruit,lead,inventory,calendar,telegram,gith *(Doc bugs noted for later: `docs/disableFeatures.md` lists `integration` but the settings category uses `integrations`; `cards` vs plugin id `card`; `training` vs feature `trainings`. Singular/plural mismatches mean those documented tokens silently match nothing.)* -## 3. Which HIDE-list apps are actually launcher tiles +## 3. Which HIDE-list apps are actually visible tiles (source-verified) -Only **6** of the handoff's HIDE list register a top-level `workbench.class.Application` with `hidden: false` (i.e. are shown-by-default tiles): +A tile shows in the launcher only if it **both** registers a `workbench.class.Application` with `hidden: false` **and** its `PluginConfiguration.enabled` is `true` in `models/all/src/index.ts` (an `enabled: false` plugin has its `Application` create-tx pruned by `pluginFilterTx`, since `defaultFilter` includes `workbench.class.Application`). Against both conditions, only **3** HIDE-list apps are actually shown by default: -| App | Registration | Shown by default | -|---|---|---| -| `recruit` | `models/recruit/src/index.ts` | yes | -| `hr` | `models/hr/src/index.ts` | yes | -| `lead` | `models/lead/src/index.ts` | yes | -| `inventory` | `models/inventory/src/index.ts` | yes | -| `board` | `models/board/src/index.ts` | yes | -| `love` (Office) | `models/love/src/index.ts` | yes | +| App | `Application.hidden` | `PluginConfiguration.enabled` | Shown by default? | +|---|---|---|---| +| `recruit` | false (`models/recruit/src/index.ts:129`) | true (`models/all/src/index.ts:234`) | **yes — needs hiding** | +| `hr` | false (`models/hr/src/index.ts:192`) | true (`models/all/src/index.ts:304`) | **yes — needs hiding** | +| `love` (Office) | false (`models/love/src/index.ts:255`) | true (`models/all/src/index.ts:395`) | **yes — needs hiding** | +| `lead` | false | **false** (`models/all/src/index.ts:259`) | no — already pruned | +| `inventory` | false | **false** (`models/all/src/index.ts:283`) | no — already pruned | +| `board` | false / `hidden:true` cfg | **false** (`models/all/src/index.ts:340`) | no — already pruned | -The rest of the HIDE list register **no launcher Application** and therefore need no hiding: `calendar` (the tile users see is Time/Planner + Team), `telegram`, `github` (injects a "Pull Requests" special *inside* Tracker), `gmail`, `mail`, `huly-mail`, `billing`, `payment`, `achievement`, `rating`, `support`, `recorder`, `bitrix`, `ai-assistant`, `ai-bot`, `openai`, `analytics-collector`. +The remaining HIDE-list apps register **no launcher Application** and need no hiding: `calendar` (the tile users see is Time/Planner + Team), `telegram`, `github` (injects a "Pull Requests" special *inside* Tracker), `gmail`, `mail`, `huly-mail`, `billing`, `payment`, `achievement`, `rating`, `support`, `recorder`, `bitrix`, `ai-assistant`, `ai-bot`, `openai`, `analytics-collector`. -So the real runtime-hide scope is just those **6 tiles**. +**So the real app-hide scope is just 3 tiles — `recruit`, `hr`, `love`.** Most of the handoff's HIDE list is already handled by upstream defaults (`enabled:false`) or was never a launcher app. (Note: this corrects an earlier draft of this doc that listed 6 "shown by default" tiles — `lead`/`inventory`/`board` register apps but are already off.) -## 4. Recommended next pass — how to actually hide the 6 tiles (choose one) +## 4. Recommended next pass — how to actually hide the 3 tiles (choose one) **Option A — `ExcludedApplications` config plumbing (reversible, all-users, small code add).** -`Workbench.svelte` already excludes `workbench.metadata.ExcludedApplications`, but **nothing sets it** — only `ExcludedApplicationsForAnonymous` is wired to config (`EXCLUDED_APPLICATIONS_FOR_ANONYMOUS` in `dev/prod/src/platform.ts` + `pods/front/src/__start.ts`). Mirror that wiring: add an `EXCLUDED_APPLICATIONS` config key that `setMetadata(workbench.metadata.ExcludedApplications, [...])` with the Refs of the 6 apps. ~3 small edits (platform.ts, front `__start.ts`, desktop), fully reversible via config, hides tiles for all logged-in users. *Slightly beyond "config-only" (adds plumbing), but no model/migration change.* +`Workbench.svelte` already excludes `workbench.metadata.ExcludedApplications`, but **nothing sets it** — only `ExcludedApplicationsForAnonymous` is wired to config (`EXCLUDED_APPLICATIONS_FOR_ANONYMOUS` in `dev/prod/src/platform.ts` + `pods/front/src/__start.ts`). Mirror that wiring: add an `EXCLUDED_APPLICATIONS` config key that `setMetadata(workbench.metadata.ExcludedApplications, [...])` with the Refs of the 3 apps (`recruit.app.Recruit`, `hr.app.HR`, `love.app.Love`). ~3 small edits (platform.ts, front `__start.ts`, desktop), fully reversible via config, hides tiles for all logged-in users. *Slightly beyond "config-only" (adds plumbing), but no model/migration change.* **Option B — `PluginConfiguration.enabled=false` (the handoff's deferred build-time path).** -Set `enabled: false` for the 6 plugins in `models/all/src/index.ts` (+ handle `migration.ts`). This is the upstream-intended way to remove apps and also drops their model txs. It's a model/build-time change → matches the handoff's "Defer: build-time stripping until the app set is validated running." +Flip `enabled: false` for just `recruit`/`hr`/`love` in `models/all/src/index.ts` (lines 234/304/395) — the same one-word change upstream already applies to `lead`/`inventory`/`board`. This is the upstream-intended way and also drops their model txs; a model/build-time change → matches the handoff's "Defer: build-time stripping until the app set is validated running." Lowest-footprint option and consistent with how the codebase already gates optional apps. **Not recommended:** per-user `HiddenApplication` (not global); `branding.json` (cannot hide apps).