hcengineering · futurebuildai · Jul 16, 2026 · Jul 16, 2026 · Jul 16, 2026 · Jul 16, 2026
diff --git 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
@@ -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/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,33 @@
+# CLAUDE.md — HH Shade (project memory)
+
+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).
+
+- **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) · **`<Org> 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 <branch>`. 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/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
 
-<sub><sup>&copy; 2025 <a href="https://hardcoreeng.com">Hardcore Engineering Inc</a>.</sup></sub>
+<sub><sup>HH Shade / 4C Shade is a fork of the Huly Platform. Upstream platform &copy; 2025 <a href="https://hardcoreeng.com">Hardcore Engineering Inc</a>.</sup></sub>
diff --git 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
@@ -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/DECISION-LOG.md 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, `<Org> Shade` instances); leaves "Prism" free as the coordinator agent. |
+| D3 | **Naming = `<Org> 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 `<Org> 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.