Helpthread · zaridan · Jul 24, 2026 · Jul 24, 2026 · coderabbitai · Jul 24, 2026
@@ -1,6 +1,6 @@
 # Helpthread — engine repo
 
-Helpthread is an open-source serverless helpdesk (AGPL-3.0 core; a Resonant IQ, Inc. product). **CHARTER.md is the constitution** — read it before substantive work.
+Helpthread is open-source support infrastructure (AGPL-3.0 core; a Resonant IQ, Inc. product). **CHARTER.md is the constitution** — read it before substantive work.
 
 ## Delegation ladder
 
@@ -16,8 +16,12 @@ Shared rule (mirrored from the resonantiq canonical doc) — imported so it load
   - **postal-mime** (MIT-0) — modern serverless MIME parsing; the parsing dependency.
   - **Chatwoot** (MIT core; the `enterprise/` folder is NOT MIT — exclude it) — behavioral/feature reference, adaptable with attribution.
   - Modern TS/AI helpdesks (e.g. antiwork/helper) may be *looked at* for UX/AI patterns, but **their code is not adapted unless a permissive LICENSE is confirmed** — as of 2026-07-10 helper's and cossistant's licenses did not resolve on GitHub, so: look-only.
-- **FreeScout's role: a window into the Help Scout experience, nothing more.** Help Scout (closed SaaS) is the ease-of-use North Star; FreeScout is the open, self-hostable pane of glass we use to *model the interface* toward that bar. It is a UX/experience reference, never a code source. Its AGPL source is never read in a Helpthread session (the operating habit lives in `CLAUDE.local.md`).
-- Behavior is specified from RFCs, public documentation, and — where already captured — the black-box fixtures; we do not observe FreeScout further.
+- Product and interface decisions are governed by Helpthread's charter and specifications,
+  not by competitor parity. Existing black-box observations may provide evidence for a
+  behavior, but they do not define the product. Copyleft-licensed projects are never code
+  sources and their source is not read in a Helpthread development session.
+- Behavior is specified from RFCs, public documentation, and — where already captured —
+  black-box fixtures.
 - Every substantive change gets real human review before merge — ordinary PR review, preserved in git history. This is also what keeps AI-assisted work copyrightable; a rubber stamp doesn't meet that bar.
 
 ## Coding discipline
@@ -31,10 +35,10 @@ Adapted in our own words from Andrej Karpathy's observations on LLM coding pitfa
 
 ## Workflow
 
-- Branches: `<type>/ht-<ticket>-<kebab-desc>` (Jira project **HT**). PRs to `main`; `main` stays releasable (charter invariant #4). No direct pushes to `main` after Phase 0.
+- Branches: `<type>/<kebab-description>`. PRs to `main`; `main` stays releasable. No direct pushes to `main` after Phase 0.
 - Commit author email stays the noreply address already set in `.git/config` (GitHub email-privacy blocks the real one).
 - Delegate work to subagents on the cheapest capable model: Haiku for mechanical, Sonnet for standard implementation, top-tier only for correctness-critical reasoning.
-- Mail semantics are sacred (charter §2, invariant #5): changes require fixture-proven equivalence or explicit written justification. Verify against reality before claiming done; put the evidence in the PR.
+- Mail semantics are sacred under the charter's "Conversation integrity" rule: changes require fixture-proven equivalence or explicit written justification. Verify against reality before claiming done; put the evidence in the PR.
 
 ## Vocabulary
 
@@ -44,7 +48,7 @@ Adapted in our own words from Andrej Karpathy's observations on LLM coding pitfa
 
 ## UI fidelity (TJ, 2026-07-12)
 
-The Agent Inbox UI's pixel source of truth is the Claude Design prototype — `Helpthread App.dc.html` in the "Helpthread Agent Inbox Design" project (the "Helpthread" design-system project carries the same components). **The dogfood site must match it exactly — the whole designed surface, not a subset.** Any deviation — visual, copy, or interaction — requires TJ's explicit sign-off. Remaining gaps are tracked as the fidelity checklist on [HT-23](https://resonantiq.atlassian.net/browse/HT-23); the ticket is not done until the checklist is.
+The Agent Inbox UI's pixel source of truth is the Claude Design prototype — `Helpthread App.dc.html` in the "Helpthread Agent Inbox Design" project (the "Helpthread" design-system project carries the same components). **The dogfood site must match it exactly — the whole designed surface, not a subset.** Any deviation — visual, copy, or interaction — requires TJ's explicit sign-off. The work is not complete until the maintained fidelity checklist is clear.
 
 **Design and app reconcile in both directions (TJ, 2026-07-20).** The two are one system, and neither is allowed to silently drift from the other:
 

@@ -4,7 +4,7 @@ Thanks for your interest this early. **Helpthread is not accepting external code
 
 ## Why not yet
 
-Helpthread's core is AGPL-3.0, and contributions are accepted under the [Developer Certificate of Origin](https://developercertificate.org/) — you sign off your commits (`git commit -s`), you keep your copyright, and there is no CLA and never will be. Because contributors keep their copyright, the plugin exception that draws the line between the AGPL core and commercial modules (see [CHARTER.md](CHARTER.md) §3) effectively cannot be broadened once outside code lands. **That exception text isn't counsel-final yet.** Until it is, we can't responsibly merge external code — not because your work wouldn't be welcome, but because merging it would freeze legal text we're still getting right, and we'd rather tell you up front than leave a PR hanging.
+Helpthread's core is AGPL-3.0, and contributions are accepted under the [Developer Certificate of Origin](https://developercertificate.org/) — you sign off your commits (`git commit -s`), you keep your copyright, and there is no CLA and never will be. Because contributors keep their copyright, the [module API exception](legal/module-api-exception.md) that draws the line between the AGPL core and commercial modules effectively cannot be broadened once outside code lands. **That exception text isn't counsel-final yet.** Until it is, we can't responsibly merge external code — not because your work wouldn't be welcome, but because merging it would freeze legal text we're still getting right, and we'd rather tell you up front than leave a PR hanging.
 
 ## What you can do now
 

@@ -0,0 +1,41 @@
+# Helpthread Governance
+
+This document describes how the Helpthread project is governed today. It may evolve
+without changing the project’s [Founding Charter](CHARTER.md).
+
+## Maintainer model
+
+Helpthread currently uses a lead-maintainer governance model. One maintainer is
+accountable for the coherence of the project and has final authority over product,
+architecture, release, and contribution decisions.
+
+That authority is stewardship. It does not transfer ownership of contributors’ work
+or create private capabilities within the open core.
+
+## Project stewardship
+
+Resonant IQ, Inc. stewards:
+
+- the Helpthread name and marks;
+- the official repository and distribution channels;
+- the official marketplace; and
+- its own contributions.
+
+Contributors retain copyright in their work. Contribution and licensing requirements
+are documented in [CONTRIBUTING.md](CONTRIBUTING.md) and
+[legal/README.md](legal/README.md).
+
+## Ordinary decisions
+
+Implementation and product decisions follow the normal issue and pull-request process.
+Current workflow requirements belong in [CONTRIBUTING.md](CONTRIBUTING.md), not the
+charter.
+
+## Charter amendments
+
+The amendment process is defined by the charter. A proposed amendment must identify
+the affected principle, explain why the current charter no longer produces the right
+decision, record alternatives, and state the final decision explicitly.
+
+Historical constitutional decisions are indexed in
+[docs/decisions/README.md](docs/decisions/README.md).
@@ -1,19 +1,35 @@
 # Helpthread
 
-Open-source, serverless helpdesk — shared inbox, threaded email conversations, knowledge base — for teams who live on Vercel and Supabase. Aimed at the ease of use Help Scout set the bar for, fully owned by the operator. FreeScout proved the self-hosted market is real; Helpthread is built for it on modern rails.
+**Open-source support infrastructure.**
 
-> **Status: early and pre-release.** This repository is being built in the open from its first day. Today it holds the project's constitution ([CHARTER.md](CHARTER.md)), behavioral specifications, a test-fixture harness, and the platform interfaces — **not yet a runnable product.** It is dogfooded first, as [Resonant IQ](https://resonantiq.app)'s own support system, before it's anything anyone else should deploy. Watch or star to follow along; expect things to move and change.
+Helpthread provides the foundation upon which support systems are built: durable
+conversations, trustworthy email threading, an operator inbox, public APIs and events,
+and an extension model available equally to first-party and community software.
 
-## What's here now
+It is serverless-native and optimized first for Vercel and Supabase, while keeping
+platform services behind Helpthread-owned interfaces. Organizations deploy Helpthread
+into infrastructure they choose and control.
 
-- **[CHARTER.md](CHARTER.md)** — the founding document: vision, principles, licensing, architecture, roadmap. Read this first.
-- **`specs/`** — behavioral specifications (the conversation API contract, mail threading) that the engine will be built and tested against.
-- **`fixtures/`** — a black-box test harness and recorded fixtures that form the mail engine's acceptance suite.
-- **`src/providers/`** — the platform-provider interfaces (queue, scheduler, storage, inbound email) the engine depends on, keeping it Vercel-first but not Vercel-only.
+> **Status: pre-release and dogfooded in production.** Helpthread is developed by
+> Resonant IQ, Inc. and runs the company's support operation today, but it is not ready for general deployment. See
+> [STATUS.md](STATUS.md) for the current product surface and roadmap.
+
+## Start here
+
+- **[Founding Charter](CHARTER.md)** — identity, principles, and project commitments
+- **[Architecture](docs/architecture/README.md)** — the map to current technical contracts
+- **[Status](STATUS.md)** — what is live, underway, and deferred
+- **[Governance](GOVERNANCE.md)** — how project decisions are made today
+- **[Legal and licensing](legal/README.md)** — the AGPL core and commercial-module boundary
+- **[`specs/`](specs/)** — the maintained behavioral and product contracts
+- **[`fixtures/`](fixtures/)** — the mail engine's black-box acceptance suite
 
 ## Architecture in one breath
 
-TypeScript on Vercel (Fluid Compute, Workflows, Queues, Cron — no daemons, nothing stays resident) plus Supabase (Postgres, Auth, Storage, Realtime). Inbound mail arrives by push webhook where the provider offers one, or by a bounded scheduled fetch where it doesn't — either way as an invocation that ends, never a process sitting in a loop. Threading authority lives on the outbound side: signed reply tokens in the Message-IDs the engine emits. See the charter for the reasoning.
+TypeScript on Vercel plus Supabase for Postgres, authentication, storage, and realtime.
+Inbound mail arrives through push delivery and bounded reconciliation rather than a
+long-running poller. Signed reply tokens minted into outbound messages give Helpthread
+verifiable threading authority. See the [architecture overview](docs/architecture/README.md).
 
 ## Development
 
@@ -33,8 +49,11 @@ Scripts:
 
 ## Contributing
 
-Not accepting external contributions yet — see [CONTRIBUTING.md](CONTRIBUTING.md). Issues and discussion are welcome.
+Helpthread is not accepting external code contributions yet. Issues and discussion are
+welcome; see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 
-[AGPL-3.0](LICENSE) for the core. © Resonant IQ, Inc. Commercially-licensed first-party modules will come later via a marketplace; the core stays free software, forever. See the charter's licensing section.
+[AGPL-3.0](LICENSE) for the core. © Resonant IQ, Inc. Commercial modules add to the
+core; they do not subtract from it. See
+[legal and licensing](legal/README.md).