8000 docs: no-auth warning up front, honest breadth wording, drop pre-extraction copy (#242) by simon-inkie · Pull Request #243 · simon-inkie/inkie-deck · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 77 additions & 0 deletions .specs/242-first-impression-fixes/SPEC.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# #242: Clarify Deck's first impression

- Issue: https://github.com/simon-inkie/inkie-deck/issues/242
- Branch: `first-impression-fixes`
- Started: 2026-11-19

## TL;DR
Make Deck's authentication boundary visible up front and describe the harnesses
that the repository actually supports. Replace legacy product wording without
changing behaviour or compatibility identifiers.
Also fix nested links in the home page Needs you rows, and make the demo and
public repository install guidance clear.

## Scope
In scope:
- README and install guidance for loopback and external access control.
- README claims about CLI harnesses and the experimental ACP client.
- Legacy shorthand and tailnet-only wording in copy, comments and matching tests.
- Valid, independently usable row and ticket links in the Needs you queue.

Out of scope:
- Authentication, runtime wiring, compatibility identifiers, artwork and
unrelated cold-read findings.

## Test plan
- Run the affected Vitest tests without live agents or listening ports.
- Run `pnpm typecheck`, `pnpm check:boundaries`, `pnpm check:licence`,
`pnpm check:lib-version`, the direct dash scan and `git diff --check`.
- Run the leak gate, supplying an explicit file list if automatic discovery fails.

## Follow-ups
None.

## Log
### 2026-11-19: Set the copy-only scope
- What changed: documented the deployment boundary, harness claims and legacy copy to update.
- Why: the cold read found that the first screen overstated support and did not explain who could reach Deck. The CLI paths have scaffolds and launchers; ACP has only a test adapter and no production caller.
- Supersedes: nothing, additive.
- Commits: pending

### 2026-11-19: Update and verify the copy
- What changed: aligned the README and install warnings, qualified runtime support,
and replaced the old wording in the UI, diagnostics and comments.
- Why: make the deployment and support limits clear without changing behaviour.
All 406 focused tests passed. Typecheck, package boundaries, licence, library
version, dash and whitespace checks passed. Git discovery in the leak gate
was blocked by the sandbox; an explicit list of regular files passed.
- Supersedes: nothing, additive.
- Commits: ba0c957 docs: no-auth warning up front, honest breadth wording, drop pre-extraction copy (#242)

### 2026-11-19: Pick up fresh-clone findings
- What changed: extending the existing branch with a focused Needs you link fix,
a regression test and Quick install documentation corrections.
- Why: the row nests a ticket anchor inside its thread link, causing invalid
markup and hydration mismatches. The demo path and public clone instructions
also need to be clear to new readers.
- Supersedes: the copy-only scope above; this also fixes row markup.
- Commits: pending

### 2026-11-19: Fix row links and public install guidance
- What changed: replaced the wrapping row anchor with a covering native link
beside the ticket anchor, preserving layout, independent navigation and
keyboard access. Added a rendered-row regression test. Quick install now
offers the fixture demo without an AI CLI, repeats the access-control warning
with the existing install anchor, and distinguishes live-agent prerequisites.
Removed the obsolete private-repository sign-in paragraph.
- Why: valid sibling links avoid the hydration mismatch while retaining native
link behaviour. New readers can try Deck without configuring an agent or
signing in to clone a public repository. The remaining private wording in
the searched documentation describes file permissions and implementation
details, not repository visibility.
- Validation: all 52 affected tests passed, along with typecheck, boundaries,
licence, library-version, direct dash, ASCII and whitespace checks. The
working-tree leak scan passed. History and commit-message leak scans failed
on existing reachable history; no Git history was changed by this work.
- Supersedes: nothing, additive.
- Commits: b6fe31f fix: nested link on the home page, demo quick start, stale private wording, no-auth note in quick install (#242)
34 changes: 12 additions & 22 deletions INSTALL.md
10BC8
Original file line number Diff line number Diff line change
Expand Up @@ -23,21 +23,16 @@ boundary is marked where you reach it.

## Read this before you put Deck on a network

**Deck has no login, no password, and no authentication of any kind.** There
is no user model, no session, no access control in the application at all.
**Deck has no authentication and binds to loopback by default.** There is no
login, user model, session or access control in the application itself.
Anyone who can reach the port can read every message in your inbox, answer
decision cards as you, and type into your agents' terminal sessions.

That is a reasonable trade for the deployment it was written for: one person,
one machine, bound to loopback or reachable only over a private network with
authentication in front of it. It is not a defensible position anywhere else,
and it will not become one by accident. There is no decision yet about
building an authentication layer, so treat "who can reach this port" as the
entire security model, because today it is.

The production launcher binds loopback by default and says so at boot. Every
step below that widens that bind says this again, in the place where you would
be about to do it.
Keep Deck on loopback for local use. Before anyone else can reach it, put it
behind your own access control, such as a VPN, a restricted tailnet or a
reverse proxy with authentication. Do not expose the Deck port directly in
ways that bypass that access control. Host and origin checks do not authenticate
users. See [Reaching it from another machine](#reaching-it-from-another-machine).

## How this document is tested

Expand Down Expand Up @@ -404,11 +399,6 @@ above ask for:
git clone https://github.com/simon-inkie/inkie-deck.git && cd inkie-deck
```

While the repository is private, that clone needs you signed in to GitHub.
Install the GitHub CLI (`gh`) and run `gh auth login` inside the same Linux
environment you are installing in, which on Windows means inside Ubuntu, not in
PowerShell. Delete this paragraph once the repository is public.

This block is the one exception to "executed from this document": the rig
copies the tree into its container instead of cloning it, so it is declared
as skipped in `rig/install-plan.mjs`, with the reason.
Expand Down Expand Up @@ -691,11 +681,11 @@ shell variable does not survive one.
Anyone who can open Deck through an approved Host can message your agents.
Scheduled jobs have a separate admin check, covered under Scheduled nudges.

Skip this unless you need it. Deck binds loopback by default and that default
is doing real work: **there is no authentication in front of the thing you are
about to publish**, so read the warning at the top of this document again
before you run this, and put access control (a reverse proxy, or a private
network that authenticates its own members) in front of it.
Skip this unless you need it. Deck binds to loopback by default and has no
authentication. Set up your own access control before making Deck reachable,
as described in the [deployment boundary](#read-this-before-you-put-deck-on-a-network).
If a proxy or tunnel can reach Deck on loopback, leave the bind unchanged.
Otherwise, widen the bind only if access to the port is restricted:

```sh
echo "HOST=0.0.0.0" >> packages/deck/.env
Expand Down
52 changes: 35 additions & 17 deletions README.md
< 10BC8 /tr>
Original file line number Diff line number Diff line change
@@ -1,13 +1,19 @@
# Inkie Deck

**One deck for every harness and every model.**
**One inbox for your AI agent team.**

Inkie Deck is a local-first control room for your AI agents. Run Claude Code,
Codex and Antigravity side by side, with many more harnesses coming very soon,
and bring every decision and action back to one place, as cards.
Codex and Antigravity side by side, and bring their decisions and actions back
to one place, as cards.
With [the Brain](https://github.com/simon-inkie/inkie-the-brain), our open source
long-term memory, your agents [remember across sessions](#give-your-agents-a-memory-that-lasts).

**Deck has no authentication and binds to loopback by default.** Keep it local
unless you put it behind your own access control, such as a VPN, a restricted
tailnet or a reverse proxy with authentication, before anyone else can reach it.
See the [deployment boundary](INSTALL.md#read-this-before-you-put-deck-on-a-network)
and [Quick install](#quick-install).

Open source under the [Apache-2.0 licence](LICENSE); [contributions are welcome](CONTRIBUTING.md).

> Running ten agents at once broke my brain. Every window wants an answer:
Expand Down Expand Up @@ -36,24 +42,24 @@ thread.

*The decision, your answer and the agent's follow-up, kept together.*

## One deck, any harness, any model

Most tools lock you into one vendor. Deck sits above the harness, so you can
pick the best model for each job and run every agent through one inbox, one
Needs you queue and one project board.
## Supported harnesses

Where it is today, plainly:
The CLI harnesses verified by the scaffolding and launcher tests in
[`packages/base`](packages/base) share one inbox, one Needs you queue and one
project board. Available models depend on the harness you use.

| Harness | Today |
| --- | --- |
| Claude Code | Fully supported: one-command setup, generated persona files, persona checks, live check, inbox delivery. |
| Claude Code | Default for one-command setup: generated persona files, persona checks, live check and inbox delivery. |
| Codex | Supported: `--runtime codex` creates the agent with an `AGENTS.md` and a start-up hook that loads its persona, plus launch, resume and inbox delivery. Live check is opt-in. |
| Antigravity | Supported: `--runtime agy` creates the agent with a `GEMINI.md` built from its persona files, plus launch, resume and inbox delivery. Live check is opt-in. |
| Antigravity (Gemini) | Supported: `--runtime agy` creates the agent with a `GEMINI.md` built from its persona files, plus launch, resume and inbox delivery. Live check is opt-in. |

Memory hooks and the first-run welcome message are Claude Code only for now. Many more harnesses are coming very soon.
Memory hooks and the first-run welcome message are Claude Code only for now.
Support for more harnesses is planned.

An Agent Client Protocol (ACP) client has also landed, the groundwork for
plugging in any agent that speaks ACP.
Deck contains an experimental Agent Client Protocol (ACP) client exercised
with a scripted test adapter only. It is not wired into the running app and
does not provide support for real ACP agents yet.

## See the work, not a description of it

Expand Down Expand Up @@ -88,7 +94,8 @@ review panel, and type or dictate replies (optional
## Not just for code

Deck runs my own business every day: marketing, customer outreach, support,
CRM hygiene and code. If an agent can do the work, you can manage it from Deck.
CRM hygiene and code. Agents on the supported harnesses can bring decisions
and actions from that work back to Deck.

## Built in daily use, not in a lab

Expand All @@ -100,7 +107,7 @@ open source version myself. It looks simple. Underneath it is not, and that is
the point: the complexity is the tool's problem, not yours.

It is built to be built on. Your agents can extend it with you, and a plugin
system is coming.
system is planned.

## Give your agents a memory that lasts

Expand Down Expand Up @@ -141,7 +148,18 @@ thread. Go and make something good, and take it easy on your head.

## Quick install

**Before you start:** Node `^22.13.0 || >=24.0.0`, pnpm `10.34.5` via Corepack, and the Claude Code CLI installed and signed in. See [prerequisites](INSTALL.md#1-prerequisites) for system packages.
Deck has no authentication; put it behind your own [access control](INSTALL.md#read-this-before-you-put-deck-on-a-network) before anyone else can reach it.

**Try the demo, no AI CLI needed:** from your clone, with Node and pnpm installed:

```sh
pnpm install && pnpm dev
```

Open <http://localhost:4242> for the interface with throwaway fixture data.
See [Try it](INSTALL.md#3-try-it).

**For Quick setup with live agents:** Node `^22.13.0 || >=24.0.0`, pnpm `10.34.5` via Corepack, and the Claude Code CLI installed and signed in. See [prerequisites](INSTALL.md#1-prerequisites) for system packages.

Run as your own user, not as root:

Expand Down
2 changes: 1 addition & 1 deletion packages/deck/app/components/AppShell.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -232,7 +232,7 @@ export function AppShell({ agents, needsItems, needsCount, workCards, tmuxOn = t
>
{/* Mobile UX: the full wordmark squeezed the
thread identity + view toggle off-screen on phones. */}
<span className="md:hidden">MC</span>
<span className="md:hidden">Deck</span>
<span className="hidden md:inline">Inkie Deck</span>
</Link>
{instanceLabel ? (
Expand Down
8 changes: 4 additions & 4 deletions packages/deck/app/components/RouteErrorPanel.tsx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/**
* RouteErrorPanel - the shared error surface for route-level ErrorBoundaries.
*
* MC must stay usable when a route fails, so an error must never be a dead
* Deck must stay usable when a route fails, so an error must never be a dead
* end. Two principles:
*
* 1. SCOPED BLAST RADIUS: every content route under the shell exports an
Expand All @@ -10,9 +10,9 @@
* sidebar + nav keep working. Only a failure in the shell/root itself
* falls back to the full-page root boundary.
*
* 2. HONEST MESSAGING: MC is a tailnet-only internal tool - showing the real
* error message in production is a feature, not a leak. The operator (or the
* agent they paste it to) needs the actual failure text, not "Oops".
* 2. USEFUL DIAGNOSTICS: Show the actual failure text so the operator can
* diagnose it. Deck relies on loopback or external access control (see
* INSTALL.md); the error panel does not restrict who can see the details.
*
* Pure presentational: no fs, no env.
* ASCII only - no em-dashes.
Expand Down
4 changes: 2 additions & 2 deletions packages/deck/app/lib/activity.server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
* file.
*
* ONE file, written by ONE external producer (a 60s sweep script), read
* by TWO independent consumers: this seam and the `activity` query CLI. MC only
* by TWO independent consumers: this seam and the `activity` query CLI. Deck only
* ever reads it. There is no write path in this module, deliberately: the pin
* override the plan calls for (section 5) is the CLI's `activity pin`, and
* adding a second writer to a file whose producer merges its own prior state
Expand Down Expand Up @@ -167,7 +167,7 @@ function offline(
* next diagnosis start from scratch.
*
* A `swept` timestamp in the FUTURE is treated as fresh, not stale: negative
* age means clock skew between the sweep host and MC (same box today, but the
* age means clock skew between the sweep host and Deck (same box today, but the
* failure mode of calling a live engine dead is worse than the reverse, and the
* banner would be nonsense - "offline since" a time that has not happened).
*/
Expand Down
6 changes: 3 additions & 3 deletions packages/deck/app/lib/activity.shared.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
* panel.
*
* The producer is an external sweep script, a deterministic 60s
* sweep that writes ONE file, `$ACTIVITY_ROOT/activity.json`. MC is a
* sweep that writes ONE file, `$ACTIVITY_ROOT/activity.json`. Deck is a
* READ-ONLY consumer of it (the query CLI is the other one). This module owns
* the wire types and every pure decision made about them; activity.server.ts
* owns the env + fs half.
Expand Down Expand Up @@ -526,7 +526,7 @@ export function parseActivityDocument(text: string): ParseActivityResult {
// Roster join
// ---------------------------------------------------------------------------

/** Signal used on rows MC synthesises for a live window the sweep did not cover. */
/** Signal used on rows Deck synthesises for a live window the sweep did not cover. */
export const NOT_SWEPT_SIGNAL = "not-swept";

/**
Expand All @@ -543,7 +543,7 @@ export const NOT_SWEPT_SIGNAL = "not-swept";
*
* Order: swept agents first, in the file's own order (which is the sweep's tmux
* window order), then any live window with no record. Keeping the file's order
* primary means the panel stays stable and complete even when MC itself cannot
* primary means the panel stays stable and complete even when Deck itself cannot
* reach tmux (windows === []).
*/
export function activityRows(
Expand Down
4 changes: 2 additions & 2 deletions packages/deck/app/lib/agent-model.server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,10 @@
* Picks which option set in the catalog applies to this agent.
* <AGENTS_ROOT>/<agent>/.model - the exact string passed to the runtime's
* model flag and to in-session /model. MISSING = inherit the global
* default. MC is a WRITER of this file (atomic temp + rename) and a
* default. Deck is a WRITER of this file (atomic temp + rename) and a
* reader for the configured-model display.
* <AGENTS_ROOT>/bin/model-catalog.json - option lists keyed by runtime,
* entries { id, label }. Platform-layer owned; MC only reads it.
* entries { id, label }. Platform-layer owned; Deck only reads it.
*
* AGENTS_ROOT is a NEW env var (default ~/agents, tilde expanded) because the
* existing INBOX_ROOT points at the silo tree, not the agent homes. Unlike the
Expand Down
4 changes: 2 additions & 2 deletions packages/deck/app/lib/batch-durability.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
* batch-durability.ts - stop losing composed messages that never left the browser.
*
* WHY THIS EXISTS
* Submitting in MC does not send anything. usePendingBatch holds the text in a
* Submitting in Deck does not send anything. usePendingBatch holds the text in a
* CLIENT-SIDE batch and starts a settle timer (SETTLE_MS, 18s by default;
* SAFETY_CAP_MS stretches it to 5 minutes while SUSPENDED). Only when that
* elapses does anything reach the server or touch a file.
Expand Down Expand Up @@ -80,7 +80,7 @@ export const MAX_RECOVERY_AGE_MS = 24 * 60 * 60 * 1000;
* Batches younger than this are LEFT ALONE on recovery.
*
* A live tab re-mirrors on every change, so a very recent record probably
* belongs to a session that is still composing. Without this floor, opening MC
* belongs to a session that is still composing. Without this floor, opening Deck
* in a second tab would drain the first tab's in-flight batch and send a
* half-written message on the author's behalf. Recovery is for abandoned
* sessions, and a session is only observably abandoned once it has stopped
Expand Down
Loading
Loading
0