8000 docs(readme): sales-style README, name section, screenshots and AGENTS.md (#213) by simon-inkie · Pull Request #211 · 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
56 changes: 56 additions & 0 deletions .specs/213-readme-sales-page/SPEC.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# README sales-style rewrite, name section, screenshots and a short AGENTS.md

- Issue: [#213](https://github.com/simon-inkie/inkie-deck/issues/213)
- Branch: docs/readme-sales-page
- Started: 2026-11-18

## TL;DR

The README opened with a plain description. It now opens by saying what Deck is
and showing it: a pitch paragraph, four screenshots (Needs you queue, an agent
thread with decision and action cards, the review panel with generated images
and code files, and the five-stage project board), a short "The name" section
(all hands on deck, and a deck of cards), and a capabilities list limited to what
the code ships. Everything from "Quick install" down, including the contributing
and rules sections, is unchanged. `AGENTS.md` goes from a pointer to a short
orientation (repo map, how to work, house rules); `CLAUDE.md` gets the matching
one-line tagline.

The screenshots come from richer fictional demo fixtures (a small paper-goods
shop scenario) added under `packages/deck/fixtures/demo-inbox`,
`demo-attachments` and `demo-projects`; `scripts/dev-paths.mjs` seeds them into
the sandbox when present. The existing e2e fixtures are untouched.

## Scope

In scope: README opening and name section, four images in `docs/images/`,
`AGENTS.md`, the `CLAUDE.md` tagline, the demo fixtures and the sandbox seeding.

Out of scope: install and contributing text, any app behaviour, the logo
(pending a pick), and Nudges availability (issue #212).

## Test plan

- `node scripts/leak-gate.mjs`, `git diff --check`, ASCII-only scan, and
`pnpm -C packages/deck check:dashes` on the branch.
- Full `pnpm test` on the committed tree (the dirty-tree guard fails on an
uncommitted tree by design).
- Each README claim checked against the code by an independent reviewer; four
inaccuracies found and fixed (see log).

## Log

- 2026-11-18: README opening, screenshots and AGENTS.md written.
- 2026-11-18: review fixes: dropped an advertised capability that is off on a
normal install, corrected two script and protocol paths, aligned `CLAUDE.md`.
- 2026-11-18: richer screenshots and demo fixtures added at the maintainer's
request.
- 2026-11-18: demo images replaced with two brand-style sets (a paper shop and a retro-robot tech shop, on two agents), a JSON code-preview shot and a second thread shot added; `scripts/capture-readme-screenshots.mjs` keeps the captures reproducible.
- 2026-11-18: SPEC and issue added after the automated review pointed out their
absence (retrospective; the work above predates this file).

## Follow-ups

- Add the chosen logo to the README header and favicon once picked.
- On a fresh load the reply box renders oversized until it is re-measured; worth
its own issue.
67 changes: 37 additions & 30 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,37 +1,44 @@
# inkie-deck

A web control plane for a fleet of AI agents, copied in from the working
platform and cleaned.
A local-first control room for a team of AI agents: a chat-style inbox, decision
and action cards, projects and drafts, backed by a file-based message protocol.
This file is the short orientation for AI coding agents. The rules live in one
place each, so read these before your first change:
[CONTRIBUTING.md](CONTRIBUTING.md) (rules), [DEVELOPMENT.md](DEVELOPMENT.md)
(workflow), [README.md](README.md) and [INSTALL.md](INSTALL.md) (setup).

This file is the runtime instruction file for AI coding agents. It is a pointer,
not a second rulebook: the contributing rules live in
[CONTRIBUTING.md](CONTRIBUTING.md), and the full workflow lives in
[DEVELOPMENT.md](DEVELOPMENT.md). Read both before your first change. Keeping
the rules in one place is deliberate, so nothing here can drift out of step with
what the other runtimes read.
## Map

If you are starting work on an issue, the `start-issue` skill does the
mechanical part: it creates the branch and the SPEC skeleton for you. See
[.agents/skills/start-issue/SKILL.md](.agents/skills/start-issue/SKILL.md).
- `packages/deck`: the React Router web app, with vitest unit tests and
Playwright journeys.
- `packages/base`: the agent protocol (`packages/base/docs/protocol.md`), persona templates and
the `inbox` CLI. It never imports from `packages/deck`; `pnpm check:boundaries`
enforces that.
- `.specs/<issue-number>-<slug>/`: one SPEC per ticket, written first and updated
as the work happens.
- `scripts/`: the root gates (leak, licence, lib-version) and `setup.sh`. The dash check is `packages/deck/scripts/check-dashes.mjs`.

For setting up a machine and running the checks, see [README.md](README.md)
("Development") and [INSTALL.md](INSTALL.md).
## How to work

## House rules for agents
1. Start from a GitHub issue. `start-issue`
([skill](.agents/skills/start-issue/SKILL.md)) creates the branch and the SPEC
skeleton.
2. Write or update the SPEC in the same pull request as the code. Never keep a
spec only in a chat, a ticket comment or a wiki.
Comment thread
devin-ai-integration[bot] marked this conversation as resolved.
Resolved
3. Keep changes small and focused, follow the patterns in the files you touch, and
add tests for core behaviour and for anything that can lose data or leak.
4. Before pushing, run the checks listed in CONTRIBUTING.md ("Checks a pull
request must pass"). Commit first: two suites assert the tree is clean.
5. Branch off `main`, keep each pull request to one change, and title commits
`type(scope): summary (#issue)`. Never push to `main`.
Comment thread
devin-ai-integration[bot] marked this conversation as resolved.
Resolved

- Specs live in the repo. Every ticket (GitHub issue) gets a folder
`.specs/<issue-number>-<slug>/` holding its SPEC.md, ISSUE-TEXT.md if used,
and any design notes, in the same pull request as the code. Never keep a spec
only in a chat, a ticket comment or a wiki. See
[DEVELOPMENT.md](DEVELOPMENT.md) section 2.
- No internal material (names, hosts, paths, ticket ids, addresses) may enter
the repository. `pnpm check:leaks` enforces it; read the rule comments before
extending the denylist.
- ASCII only, no em-dashes or en-dashes anywhere in the tree. This is not style:
U+2014 is the field separator in the message protocol, so a literal one in a
file is a parsing hazard. `pnpm check:dashes` enforces it.
- Sign off every commit (`git commit -s`), as [CONTRIBUTING.md](CONTRIBUTING.md)
requires; an unsigned commit fails the DCO gate.
- If you are an agent: do not push to `main`, force-push a shared branch, merge
your own pull request, or create a release unless a maintainer asked you to
in the issue or pull request.
## House rules

- No internal material (names, hosts, paths, ticket ids, addresses) in the
repository. `pnpm check:leaks` enforces it.
- ASCII only, no em-dashes or en-dashes anywhere in the tree: U+2014 is the field
separator in the message protocol. `pnpm -C packages/deck check:dashes` enforces it.
- Sign off every commit (`git commit -s`); an unsigned commit fails the DCO gate.
- Agents: do not push to `main`, force-push a shared branch, merge your own pull
request, or create a release unless a maintainer asked you to in the issue or
pull request.
3 changes: 1 addition & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
# inkie-deck

A web control plane for a fleet of AI agents, copied in from the working
platform and cleaned.
A local-first control room for a team of AI agents.

## Shared rules

Expand Down
56 changes: 52 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,56 @@
# inkie-deck
# Inkie Deck

A web control plane for a fleet of AI agents: inboxes, decision cards, briefs,
projects, tmux-backed agent sessions, and the file-based message protocol that
ties them together.
A local-first control room for your team of AI agents.

Inkie Deck runs on your machine and gives you a browser interface for working
with several agents. Talk to each agent in a chat-style inbox, then open
**Needs you** to see which decisions and actions need your attention without
reading every thread. Deck stores conversations in local files.

Inkie Deck is open source under the [Apache-2.0 licence](LICENSE).
[Contributions are welcome](CONTRIBUTING.md).

![Needs you page listing overdue and upcoming decisions from agents, with a separate section for blocked work](docs/images/needs-you.png)

*Needs you brings requests from across your agents into one view, with the most urgent items first.*

![Agent thread showing an answered decision card, the user's reply and the agent's follow-up](docs/images/agent-thread.png)

*An agent thread keeps the decision, your answer and the agent's update together.*

![A second agent's thread with a launch carousel slide shown inline and links to the kit label and a config file](docs/images/agent-thread-tech.png)

*Agents share work as inline images and links to files, so a launch carousel arrives as something you can see, not a description.*

![Review panel with a file list of generated images and code files, and a hero image previewed beside the thread](docs/images/review-panel.png)

*Files an agent produces open beside the thread: generated images, code and notes, searchable and ready to review.*

![A second agent's thread with an inline carousel slide and a link to its launch config, beside the same config open as highlighted JSON](docs/images/code-preview.png)

*Code opens in the same panel with syntax highlighting, so a config file an agent wrote can be read next to the conversation about it.*
Comment on lines +29 to +31
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔍 Code-preview caption overstates the linked workflow

The pictured JSON opens via a constructed ?doc=~/attachments/... URL. Clicking the thread's /attachments/...json link opens a new tab, not highlighted code beside the conversation.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.


![Project board with twelve cards across to do, in progress, blocked, in review and done](docs/images/project-board.png)

*The project board keeps every piece of work in one of five stages, each card showing its owner and what it is waiting on.*

## Why Deck

- **Handle requests from across your agents.** Answer decision cards and mark
action cards done without searching through conversations.
- **Track project work.** Move cards between stages on a project board and open
the details when you need context.
- **Draft and review in the browser.** Edit Markdown drafts saved in your
workspace, and open linked documents in the review panel alongside the thread.
- **Type or dictate a reply.** The compose box supports optional
[voice dictation](INSTALL.md#voice-dictation-optional) with an API key.

## The name

Deck has two sources. It is "all hands on deck": your whole team of agents,
working together on one ship. And it is a deck of cards: agents send you decision
cards and action cards, so you answer a question or tick off a task instead of
reading every thread. The cards take the cognitive load off you.

## Quick install

Expand Down
Binary file added docs/images/agent-thread-tech.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/agent-thread.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/code-preview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/needs-you.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/project-board.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/review-panel.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
{
"shop": "Spark and Relay",
"page": "/launch/bench-kits",
"launchDate": "2026-06-18T09:00:00Z",
"hero": {
"image": "tech-hero-a.png",
"alt": "Tin robot on a burst of teal, rust and mustard",
"headline": "Local tools, built to last",
"cta": { "label": "See the kits", "href": "/collections/bench-kits" }
},
"carousel": [
{ "slide": 1, "image": "tech-carousel-1.png", "caption": "Local tools, built to last" },
{ "slide": 2, "image": "tech-carousel-2.png", "caption": "Zero cloud, full control" }
],
"kits": [
{ "sku": "SR-KIT-01", "name": "Relay starter kit", "price": 34.0, "stock": 120 },
{ "sku": "SR-KIT-02", "name": "Telemetry bench kit", "price": 58.0, "stock": 64 },
{ "sku": "SR-KIT-03", "name": "Valve radio kit", "price": 72.5, "stock": 25 }
],
"freeDeliveryOver": 40,
"showCountdown": true,
"newsletterSignup": false
}
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
22 changes: 22 additions & 0 deletions packages/deck/fixtures/demo-attachments/echo/mc/SpringHero.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
// SpringHero.tsx - homepage hero for the spring stationery range.
// Two image variants so the A/B test can swap without a deploy.

type Variant = "a" | "b";

const IMAGES: Record<Variant, string> = {
a: "/images/spring-hero-a.png",
b: "/images/spring-hero-b.png",
};

export function SpringHero({ variant = "a" }: { variant?: Variant }) {
return (
<section className="spring-hero">
<img src={IMAGES[variant]} alt="Greeting cards and pressed flowers on a teal burst" />
<div className="spring-hero__copy">
<h1>Paper and petals, made to order</h1>
<p>The spring range is here: notebooks, cards and gift boxes, pressed by hand.</p>
<a className="button" href="/collections/spring">Shop the range</a>
</div>
</section>
);
}
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# The spring range is here

Twelve new pieces, all pressed and bound by hand in the studio.

- Pressed-flower notebooks in three sizes
- Seed-paper greetings cards
- A gift box that arrives ready to give

Orders placed before 2pm leave the same day.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
20 changes: 20 additions & 0 deletions packages/deck/fixtures/demo-attachments/echo/mc/spring-hero.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
/* spring-hero.css - layout for the homepage hero. */
.spring-hero {
display: grid;
grid-template-columns: 3fr 2fr;
gap: 2rem;
align-items: center;
padding: 3rem 1rem;
background: #faf4e8;
}

.spring-hero img {
width: 100%;
border-radius: 12px;
}

@media (max-width: 720px) {
.spring-hero {
grid-template-columns: 1fr;
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"campaign": "spring-range",
"links": [
{ "channel": "instagram", "url": "/collections/spring?utm_source=instagram" },
{ "channel": "newsletter", "url": "/collections/spring?utm_source=newsletter" }
]
}
45 changes: 45 additions & 0 deletions packages/deck/fixtures/demo-inbox/atlas/inbox/alex.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,3 +26,48 @@ A. That's our voice.
Homepage strapline is live with option A. It reads clean and on-brand.

---
## 2026-06-09T14:00:00Z - from: atlas - status: sent - subject: free delivery threshold
decision-id: TASK-SITE-5
blocking: false
options:
- key: A
label: "Free delivery over 40 pounds"
detail: "Nudges the average basket up from 38 pounds. Most orders would need one more card."
- key: B
label: "Keep it at 50 pounds"
detail: "Protects margin on heavy gift boxes. Fewer orders qualify."
lean: "A - small cost, and it gives the cards a reason to sit in the basket."

**The call:**
The new checkout shows a free delivery bar. Where should the line sit?

---
## 2026-06-09T14:05:00Z - from: atlas - status: sent - subject: context

The delivery bar is built and on the preview site. It only needs the number.

---
## 2026-06-09T14:30:00Z - from: atlas - status: read - subject: Spark and Relay launch page

The bench-kit launch page for Spark and Relay is on its own preview site. Two hero options: [hero A, the tin robot](/attachments/atlas/mc/tech-hero-a.png) and [hero B, the bench oscilloscope](/attachments/atlas/mc/tech-hero-b.png). I've built it around A; say if you'd rather lead with B.

---
## 2026-06-09T14:45:00Z - from: alex - status: read - subject: Re: Spark and Relay launch page

A. The robot is the shop.

---
## 2026-06-09T15:10:00Z - from: atlas - status: sent - subject: launch carousel

Carousel for the kit launch is ready. Slide 1:

![Carousel slide 1: local tools, built to last](/attachments/atlas/mc/tech-carousel-1.png)

Slide 2 is [zero cloud, full control](/attachments/atlas/mc/tech-carousel-2.png). The page reads its hero, slides and kit list from [the launch config](/attachments/atlas/mc/spark-relay-launch.json), so swapping a slide is a one-line change.

---
## 2026-06-09T15:40:00Z - from: atlas - status: sent - subject: kit box label

Kit box label is ready on the same 90mm stock as the gift boxes, so Briar can print both on one run: [kit box label](/attachments/atlas/mc/tech-product-label.png).

---
8 changes: 8 additions & 0 deletions packages/deck/fixtures/demo-inbox/briar/inbox/alex.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,3 +22,11 @@ or cap daily orders and let the backlog clear gracefully?
Current backlog is fine, under ten parcels. This is purely launch-week insurance, not a live problem.

---
## 2026-06-09T12:00:00Z - from: briar - status: sent - subject: sign the courier renewal
action-id: TASK-PACK-4
priority: urgent
ticket: SHOP-9

The courier contract renews on Friday and needs your signature, not mine. Same rate as last year; the PDF is in your email from them.

---
Loading
Loading
0