Repository navigation
docs(readme): sales-style README, name section, screenshots and AGENTS.md (#213) #211
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
3df8bf1
docs: sales-style README opening, name section, screenshots and a sho…
simon-inkie c9270a8
docs: address review (drop Nudges bullet, fix script and protocol pat…
simon-inkie 597d30c
docs: richer README screenshots and demo fixtures (files, board, full…
simon-inkie 91b6dff
docs(readme): add SPEC for the README rewrite (#213)
simon-inkie c355f48
docs(readme): brand-style demo images, code preview and second-agent …
simon-inkie File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. | ||
| 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`. | ||
|
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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 brings requests from across your agents into one view, with the most urgent items first.* | ||
|
|
||
|  | ||
|
|
||
| *An agent thread keeps the decision, your answer and the agent's update together.* | ||
|
|
||
|  | ||
|
|
||
| *Agents share work as inline images and links to files, so a launch carousel arrives as something you can see, not a description.* | ||
|
|
||
|  | ||
|
|
||
| *Files an agent produces open beside the thread: generated images, code and notes, searchable and ready to review.* | ||
|
|
||
|  | ||
|
|
||
| *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
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||
|
|
||
|  | ||
|
|
||
| *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 | ||
|
|
||
|
|
||
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.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
23 changes: 23 additions & 0 deletions
23
packages/deck/fixtures/demo-attachments/atlas/mc/spark-relay-launch.json
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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.
Binary file added
BIN
+150 KB
packages/deck/fixtures/demo-attachments/atlas/mc/tech-product-label.png
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
22
packages/deck/fixtures/demo-attachments/echo/mc/SpringHero.tsx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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.
9 changes: 9 additions & 0 deletions
9
packages/deck/fixtures/demo-attachments/echo/mc/launch-post.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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
20
packages/deck/fixtures/demo-attachments/echo/mc/spring-hero.css
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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; | ||
| } | ||
| } |
7 changes: 7 additions & 0 deletions
7
packages/deck/fixtures/demo-attachments/echo/mc/utm-links.json
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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" } | ||
| ] | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.