factoryhub 0.1.0 → 0.1.1

package/factories/video-to-posts/flow.yaml

@@ -0,0 +1,62 @@
+flow: mindburn.flow/v1
+title: One video, a week of posts
+author: Mindburn Labs
+version: "1.0.0"
+license: MIT
+tags: [social, marketing]
+time: about 3 minutes
+inputs:
+  transcript:
+    type: longtext
+    help: "The transcript of your video, podcast or talk, pasted as it is. Keep the timestamps if it has them: each post then points back to the moment it came from."
+  about_you:
+    type: text
+    optional: true
+    help: "Who you are and who watches, for example \"I make short videos about building small apps; most of my viewers are students\". It sets the voice, not the facts."
+steps:
+  moments:
+    title: Find the moments worth posting
+    agent: analyst
+    kind: work
+    task: |
+      Read the whole transcript. First write a fact sheet: every number, name, date, result and claim the speaker states, each with the speaker's exact words and its timestamp, if the transcript has timestamps. Keep every qualifier the speaker attaches to a fact, such as "maybe", "about" or "mostly". Where the speaker corrects themselves, the corrected figure is the fact; note the correction. Where the transcript is garbled, or a figure is said two ways without a correction, mark it "unclear" instead of choosing.
+
+      Then pick the five moments most worth posting: a surprising number or result, a short story with a turn, a strong opinion, a how-to someone could copy, a mistake and its lesson. For each give a one-line title, the exact quote (under 40 words), its timestamp, and why a stranger would stop scrolling for it. Rank them, strongest first. Do not pick a moment whose point the transcript does not make. If the transcript supports fewer than five honest moments, give fewer.
+  posts:
+    title: Write the week of posts
+    agent: writer
+    kind: deliver
+    needs: [moments]
+    task: |
+      Write a week of posts from the moments, in the speaker's voice and, wherever you can, in the speaker's own words. Use about_you only for the voice and the audience, never as a source of facts. Sections, in this order:
+
+      1. **The week at a glance**: a table with columns Day (1 to 7), Channel, Moment, First line.
+      2. **X**: one thread of 4 to 6 posts built on the strongest moment, and two single posts on other moments. No post is longer than 280 characters.
+      3. **LinkedIn**: one post under 200 words whose first line works on its own.
+      4. **Short video**: a 30-second script for TikTok, Reels or Shorts: the hook to say in the first two seconds, three beats and a closing line. For each beat, give the timestamp of the original clip to cut in or, if the transcript has no timestamps, the clip's first words.
+      5. **Newsletter**: a note under 120 words that points readers to the full video, with "[ADD: link to the video]" where the link goes.
+      6. **Before you post**: every factual claim the posts make, each with the quote and timestamp it rests on; every person or company the posts name other than the speaker, so you can check they are happy to be named; and anything the speaker should double-check.
+
+      Every fact comes from the transcript, as the fact sheet records it. Never round a number, shorten a time span, make a result bigger or more certain, drop a qualifier that keeps a claim modest, name a person or quote words the speaker did not say. Where a post would be stronger with a real asset, such as a screenshot or a link, write "[ADD: what belongs here]" instead of inventing it. Add no hype the speaker did not use, and no exclamation marks or emojis unless the transcript has them. Use at most two hashtags a post.
+  check_posts:
+    title: Check every line against the transcript
+    agent: reviewer
+    kind: check
+    needs: [posts]
+    checks: posts
+    task: |
+      Compare every line of every post with the transcript and the fact sheet. Each number, time span, name, result and quote appears in the transcript with the same meaning. Nothing is rounded, shortened, made bigger or more certain, or moved to a different context, and quotes are word for word. A qualifier the speaker attached stays wherever leaving it out would make the claim sound bigger or more certain. A self-corrected figure uses the corrected value; an unclear one is not stated as fact. Send back any line the transcript does not support.
+
+      Then check the shape: all six sections are present and in order, no X post is longer than 280 characters, the LinkedIn post and the newsletter note keep to their word limits, each beat of the short-video script points to a timestamp or to the first words of a clip, and every factual claim appears in "Before you post". When you send work back, quote the post's words and the transcript's words side by side so the writer can correct them.
+  approve_posts:
+    title: Approve the posts
+    kind: approve
+    needs: [check_posts]
+    shows: posts
+    task: |
+      These go out under your name. Approve them, or say what to change: a moment to drop, a line that does not sound like you, a fact that is wrong. Nothing is posted for you: you copy what you approve.
+
+done:
+  - "Every number, time span, name and quote in the posts is in the transcript, with the same meaning."
+  - "Every post can be copied as it stands, or marks plainly what to add."
+  - "Every factual claim is listed under \"Before you post\" with the words it rests on."

package/factories/video-to-posts/mindburn.tests.yaml

@@ -0,0 +1,34 @@
+version: 1
+cases:
+  frying_pan_app:
+    name: Keeps every figure exactly as the speaker said it
+    inputs:
+      transcript: |
+        [0:00] So this is the story of how a frying pan made me build an app.
+        [0:06] Our flat group chat had 212 messages in one month. I counted. Most of them were about one frying pan that nobody would wash.
+        [0:18] There are five of us in the flat. Everyone thought they did the most dishes. Everyone was wrong, including me.
+        [0:31] I'm not a programmer. I did one coding course at school and forgot most of it. But I'd been using an AI coding assistant for small things, and I thought, okay, how hard can a dishes app be?
+        [0:47] It took me two weekends. Maybe three, if you count the weekend I spent on the logo.
+        [0:55] And that's my first lesson. I spent a whole Saturday on a logo, and not one person has ever mentioned the logo. Not one.
+        [1:06] Here's how it works, and honestly the trick is how little it does. When something needs washing, you tap one button. The app looks at who has done the fewest dishes this week and sends that one person a message. That's it. No points, no leaderboard, no badges.
+        [1:27] I tried points first. Points made it worse. One flatmate started washing single teaspoons to collect points.
+        [1:38] So here's my hot take: most chore apps fail because they turn chores into a game. Nobody in my flat wanted a game. We wanted the arguing to stop.
+        [1:50] Did it work? The group chat went from 212 messages to, I checked last night, 9 messages last month. And three of those were about pizza.
+        [2:04] Then a friend posted about it, and people from other flats started asking for it. 38 people signed up in the first week. Mostly friends of friends, to be fair. 11 of them used it again the next day, which for an app about dishes I'll take.
+        [2:22] It costs me about four, no, three pounds a month to run. Three.
+        [2:28] What I'd do differently: skip the logo, and ask my flatmates what annoyed them before writing a single line. I guessed it was fairness. It was the frying pan. It's always one frying pan.
+        [2:42] If you build something like this, start with the one message the app sends. Write that message first. Everything else is decoration.
+        [2:51] Anyway. The pan is clean. For now.
+      # Invented sample: Maya, her flat and this video do not exist. The
+      # disclosure stays out of the inputs so it does not leak into the posts;
+      # the README carries it.
+      about_you: "I'm Maya. I make short videos about building small apps; most of my viewers are students and first-time builders."
+    # Contains: the sections the flow asks for and the subject of the video.
+    # Excludes: the easy roundings of what Maya said (two weekends, maybe
+    # three; one coding course; 38 sign-ups; three pounds after a correction)
+    # and a result she never claims.
+    expect:
+      contains: ["LinkedIn", "Short video", "Newsletter", "Before you post", "frying pan"]
+      excludes: ["went viral", "in one weekend", "in a weekend", "40 people", "nearly 40", "almost 40", "never coded", "£4", "four pounds a month"]
+      min_length: 1500
+      max_length: 16000

package/factories/week-of-posts/README.md

@@ -0,0 +1,11 @@
+# X and LinkedIn posts from the facts
+
+Paste the facts sheet of a video, podcast or talk, and the transcript if you have it. You get an X thread of 4 to 6 posts, two single posts and a LinkedIn post, in your voice and wherever possible in your own words, with a list of every fact they use and the words it rests on. A checker holds every line against the facts sheet and sends back anything stronger than what you said: a rounded number, a dropped "maybe", a result made bigger. Nothing is posted for you.
+
+The facts sheet can come from "Facts from a video", or you can write your own: one fact a line, each with its timestamp or the first words of the line. "Release desk" puts these posts together with the other pieces for one approval.
+
+## Try it on the example
+
+The example is invented: Maya, her flat and her video do not exist. Its facts sheet is the one "Facts from a video" should write from her transcript. On the factory page, "Fill in the example" pastes it for you.
+
+The example is in `mindburn.tests.yaml`. With the downloaded folder, `node run.mjs --test` runs it and checks that the posts keep the sections and none of the easy roundings. Passing checks are a repeatable regression signal, not proof that every facts sheet will be handled correctly. Read the posts against your facts before you copy them.

package/factories/week-of-posts/agents/reviewer/agent.md

@@ -0,0 +1,10 @@
+---
+description: Checks work against stated criteria and sends weak work back.
+agentType: REVIEW
+---
+
+You are the reviewer. You hold one piece of work against the criteria you are given and decide whether it passes.
+
+- You judge only what is on the page and only against the stated criteria.
+- You fail work for a clear, specific breach you can point to. You never fail it for taste, or for something nobody asked for.
+- When you send work back, each reason is one concrete sentence the author can act on.

package/factories/week-of-posts/agents/writer/agent.md

@@ -0,0 +1,11 @@
+---
+description: Writes the finished words the person will use or send.
+agentType: CUSTOM
+---
+
+You are the writer. You write the finished thing the person will use: the brief, the message, the page, the report.
+
+- Plain words, short sentences, the reader's own vocabulary. No filler and no hype.
+- You keep to the sections, word limits and order the step asks for.
+- You add no fact that is not in the inputs or earlier results. Where a real asset or decision is missing, you mark the gap clearly instead of inventing it.
+- What you write should be usable as it stands.

package/factories/week-of-posts/factory.yaml

@@ -0,0 +1,12 @@
+schemaVersion: v1alpha1
+name: week-of-posts
+description: |
+  Writes an X thread, two single posts and a LinkedIn post from the facts
+  sheet of one video, podcast or talk, in the speaker's voice, saying nothing
+  the facts sheet does not say. Use after "Facts from a video", or with your
+  own list of what you said, when you want posts you can put your name to.
+repositories: []
+agentDefaults:
+  harness:
+    type: claude
+    model: sonnet

package/factories/week-of-posts/flow.yaml

@@ -0,0 +1,46 @@
+flow: mindburn.flow/v1
+title: X and LinkedIn posts from the facts
+author: Mindburn Labs
+version: "1.0.0"
+license: MIT
+tags: [social, marketing]
+time: about 2 minutes
+inputs:
+  facts:
+    type: longtext
+    help: "The facts sheet from \"Facts from a video\", or your own list of what you said: one fact a line, each with its timestamp or the first words of the line."
+  transcript:
+    type: longtext
+    optional: true
+    help: "The transcript the facts came from. With it, the posts can use your exact wording and the checker can quote it when it sends a line back."
+  about_you:
+    type: text
+    optional: true
+    help: "Who you are and who watches, for example \"I make short videos about building small apps; most of my viewers are students\". It sets the voice, not the facts."
+steps:
+  posts:
+    title: Write the X thread and the LinkedIn post
+    agent: writer
+    kind: deliver
+    task: |
+      Write posts from the facts sheet, in the speaker's voice and, wherever you can, in the speaker's own words as the sheet quotes them. Use about_you only for the voice and the audience, never as a source of facts. Sections, in this order:
+
+      1. **X**: one thread of 4 to 6 numbered posts built on the strongest fact or story on the sheet, then two single posts on other facts. No post is longer than 280 characters.
+      2. **LinkedIn**: one post under 200 words whose first line works on its own.
+      3. **Facts used**: every factual claim the posts make, each with the facts-sheet ID if the sheet has IDs, its timestamp or first words, and the exact words it rests on.
+
+      Every fact comes from the facts sheet. If the transcript is given, you may take the speaker's exact wording from it, but only for facts the sheet has. Never round a number, shorten or lengthen a time span, make a result bigger or more certain, drop a qualifier that keeps a claim modest, state an opinion as a fact, work out a figure the sheet does not state, such as a percentage, or name a person the sheet does not name. A fact the sheet marks "unclear" is not stated as settled. Where a post would be stronger with a real asset, such as a screenshot or a link, write "[ADD: what belongs here]" instead of inventing it. Add no hype the speaker did not use, and no exclamation marks or emojis unless the sheet quotes them. Use at most two hashtags a post.
+  check_posts:
+    title: Check every line against the facts sheet
+    agent: reviewer
+    kind: check
+    needs: [posts]
+    checks: posts
+    task: |
+      Compare every line of every post with the facts sheet, and with the transcript if it is given. Each number, time span, name, result and quote is on the facts sheet with the same meaning. Send back any line that says more than the source: a rounded or worked-out figure, a shorter or longer time span, a result made bigger or more certain, a dropped qualifier such as "maybe", "about" or "mostly", an opinion stated as fact, a fact marked "unclear" stated as settled, or a quote that is not word for word. Send back any fact the sheet does not have, even one that sounds harmless.
+
+      Then check the shape: the three sections are present and in order, the thread has 4 to 6 numbered posts and there are two single posts, no X post is longer than 280 characters, the LinkedIn post is under 200 words, and every factual claim appears under "Facts used". When you send work back, quote the post's words and the source's words side by side so the writer can correct them.
+done:
+  - "Every number, time span, name and quote in the posts is on the facts sheet, with the same meaning."
+  - "No post says more than the source: nothing rounded, worked out or made more certain, and no qualifier dropped."
+  - "Every factual claim is listed under \"Facts used\" with the words it rests on."

package/factories/week-of-posts/mindburn.tests.yaml

@@ -0,0 +1,80 @@
+version: 1
+cases:
+  frying_pan_posts:
+    name: Writes posts that say no more than the facts sheet
+    inputs:
+      facts: |
+        ## Facts
+
+        | ID | Where | Fact | Exact words |
+        | --- | --- | --- | --- |
+        | F1 | [0:00] | The video is the story of how a frying pan made the speaker build an app. | "So this is the story of how a frying pan made me build an app." |
+        | F2 | [0:06] | The flat's group chat had 212 messages in one month; the speaker counted them. | "Our flat group chat had 212 messages in one month. I counted." |
+        | F3 | [0:06] | Most of those messages were about one frying pan that nobody would wash. | "Most of them were about one frying pan that nobody would wash." |
+        | F4 | [0:18] | Five people live in the flat. | "There are five of us in the flat." |
+        | F5 | [0:18] | Everyone thought they did the most dishes, and everyone was wrong, the speaker included. | "Everyone thought they did the most dishes. Everyone was wrong, including me." |
+        | F6 | [0:31] | The speaker is not a programmer: one coding course at school, most of it forgotten. | "I'm not a programmer. I did one coding course at school and forgot most of it." |
+        | F7 | [0:31] | The speaker had been using an AI coding assistant for small things. | "But I'd been using an AI coding assistant for small things" |
+        | F8 | [0:47] | The app took two weekends, maybe three counting the weekend spent on the logo. | "It took me two weekends. Maybe three, if you count the weekend I spent on the logo." |
+        | F9 | [0:55] | The speaker's first lesson: a whole Saturday went on a logo, and nobody has ever mentioned it. | "I spent a whole Saturday on a logo, and not one person has ever mentioned the logo. Not one." |
+        | F10 | [1:06] | When something needs washing, you tap one button, and the app messages the one person who has done the fewest dishes this week. | "When something needs washing, you tap one button. The app looks at who has done the fewest dishes this week and sends that one person a message." |
+        | F11 | [1:06] | The app has no points, no leaderboard and no badges. | "No points, no leaderboard, no badges." |
+        | F12 | [1:27] | Points came first and made it worse: one flatmate washed single teaspoons to collect points. | "I tried points first. Points made it worse. One flatmate started washing single teaspoons to collect points." |
+        | F13 | [1:38] | The speaker's opinion, called a hot take: most chore apps fail because they turn chores into a game. | "So here's my hot take: most chore apps fail because they turn chores into a game." |
+        | F14 | [1:38] | Nobody in the flat wanted a game; they wanted the arguing to stop. | "Nobody in my flat wanted a game. We wanted the arguing to stop." |
+        | F15 | [1:50] | The group chat went from 212 messages to 9 messages last month, and three of those were about pizza. | "The group chat went from 212 messages to, I checked last night, 9 messages last month. And three of those were about pizza." |
+        | F16 | [2:04] | After a friend posted about it, people from other flats started asking for it. | "Then a friend posted about it, and people from other flats started asking for it." |
+        | F17 | [2:04] | 38 people signed up in the first week, mostly friends of friends. | "38 people signed up in the first week. Mostly friends of friends, to be fair." |
+        | F18 | [2:04] | 11 of them used it again the next day. | "11 of them used it again the next day, which for an app about dishes I'll take." |
+        | F19 | [2:22] | Running it costs three pounds a month, after a correction. | "It costs me about four, no, three pounds a month to run. Three." |
+        | F20 | [2:28] | What the speaker would do differently: skip the logo, and ask the flatmates what annoyed them before writing a single line. They guessed fairness; it was the frying pan. | "What I'd do differently: skip the logo, and ask my flatmates what annoyed them before writing a single line. I guessed it was fairness. It was the frying pan." |
+        | F21 | [2:42] | The speaker's advice: start with the one message the app sends, and write that message first. | "If you build something like this, start with the one message the app sends. Write that message first. Everything else is decoration." |
+        | F22 | [2:51] | The pan is clean, for now. | "The pan is clean. For now." |
+
+        ## Quotes worth using
+
+        - [0:06] "Our flat group chat had 212 messages in one month. I counted." (F2)
+        - [0:55] "not one person has ever mentioned the logo. Not one." (F9)
+        - [1:06] "No points, no leaderboard, no badges." (F11)
+        - [1:27] "One flatmate started washing single teaspoons to collect points." (F12)
+        - [1:38] "We wanted the arguing to stop." (F14)
+        - [2:28] "I guessed it was fairness. It was the frying pan." (F20)
+        - [2:42] "Write that message first. Everything else is decoration." (F21)
+        - [2:51] "The pan is clean. For now." (F22)
+
+        ## Corrections and unclear
+
+        - [2:22] The running cost: the speaker says "about four, no, three pounds a month", then "Three." The corrected figure, three pounds a month, is the fact (F19).
+        - [0:47] and [0:55] The time on the logo is said two ways: "the weekend I spent on the logo" and "a whole Saturday on a logo". Unclear: quote each where it is said, and do not state how long the logo took.
+
+        ## Names
+
+        No one other than the speaker is named.
+      transcript: |
+        [0:00] So this is the story of how a frying pan made me build an app.
+        [0:06] Our flat group chat had 212 messages in one month. I counted. Most of them were about one frying pan that nobody would wash.
+        [0:18] There are five of us in the flat. Everyone thought they did the most dishes. Everyone was wrong, including me.
+        [0:31] I'm not a programmer. I did one coding course at school and forgot most of it. But I'd been using an AI coding assistant for small things, and I thought, okay, how hard can a dishes app be?
+        [0:47] It took me two weekends. Maybe three, if you count the weekend I spent on the logo.
+        [0:55] And that's my first lesson. I spent a whole Saturday on a logo, and not one person has ever mentioned the logo. Not one.
+        [1:06] Here's how it works, and honestly the trick is how little it does. When something needs washing, you tap one button. The app looks at who has done the fewest dishes this week and sends that one person a message. That's it. No points, no leaderboard, no badges.
+        [1:27] I tried points first. Points made it worse. One flatmate started washing single teaspoons to collect points.
+        [1:38] So here's my hot take: most chore apps fail because they turn chores into a game. Nobody in my flat wanted a game. We wanted the arguing to stop.
+        [1:50] Did it work? The group chat went from 212 messages to, I checked last night, 9 messages last month. And three of those were about pizza.
+        [2:04] Then a friend posted about it, and people from other flats started asking for it. 38 people signed up in the first week. Mostly friends of friends, to be fair. 11 of them used it again the next day, which for an app about dishes I'll take.
+        [2:22] It costs me about four, no, three pounds a month to run. Three.
+        [2:28] What I'd do differently: skip the logo, and ask my flatmates what annoyed them before writing a single line. I guessed it was fairness. It was the frying pan. It's always one frying pan.
+        [2:42] If you build something like this, start with the one message the app sends. Write that message first. Everything else is decoration.
+        [2:51] Anyway. The pan is clean. For now.
+      # Invented sample: Maya, her flat and this video do not exist. The
+      # disclosure stays out of the inputs so it does not leak into the result;
+      # the README carries it.
+      about_you: "I'm Maya. I make short videos about building small apps; most of my viewers are students and first-time builders."
+    # The facts sheet is the reference result of "Facts from a video" on the
+    # same transcript. Excludes: the roundings it invites, the running cost before
+    # the correction, a result she never claims and percentages she never said.
+    expect:
+      contains: ["LinkedIn", "Facts used", "frying pan"]
+      excludes: ["went viral", "in one weekend", "in a weekend", "40 people", "nearly 40", "almost 40", "never coded", "£4", "four pounds a month", "96%", "29%"]
+      min_length: 900
+      max_length: 9000

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "factoryhub",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "AI factories, shared: the open factory format, its engine, a CLI and a local MCP server, with the house factories.",
   "keywords": [
     "factoryhub",
@@ -27,6 +27,16 @@
     "url": "git+https://github.com/Mindburn-Labs/factoryhub.git"
   },
   "mcpName": "io.github.Mindburn-Labs/factoryhub",
+  "exports": {
+    ".": {
+      "types": "./packages/sdk/src/index.d.ts",
+      "default": "./packages/sdk/src/index.mjs"
+    },
+    "./engine": "./packages/engine/src/index.mjs",
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
+  "types": "./packages/sdk/src/index.d.ts",
   "engines": {
     "node": ">=22"
   },
@@ -49,6 +59,8 @@
     "packages/mcp/package.json",
     "packages/mcp/bin",
     "packages/mcp/src",
+    "packages/sdk/package.json",
+    "packages/sdk/src",
     "factories",
     "NOTICE",
     "spec/*.md",
@@ -59,7 +71,8 @@
     "lint": "eslint . && node scripts/check-links.mjs",
     "validate": "node packages/cli/bin/factoryhub.mjs validate factories/*/",
     "generate": "node scripts/generate.mjs",
-    "check": "npm run lint && npm test && npm run validate && node scripts/generate.mjs --check"
+    "check": "npm run lint && npm test && npm run validate && node scripts/generate.mjs --check && npm run check:rust",
+    "check:rust": "cargo fmt --all --check && cargo clippy --all-targets --locked -- -D warnings && cargo test --locked && cargo build --locked --target wasm32-unknown-unknown -p factoryhub-core"
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.4.0",

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factoryhub/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The factoryhub command line: validate, inspect, scaffold, pack, run and export AI factories, and find them on factoryhub.",
   "license": "Apache-2.0",
   "type": "module",

package/packages/cli/src/commands/export.mjs

@@ -7,7 +7,6 @@ import { DEFAULT_HUB } from '../../../engine/lib/hub.mjs';
 
 export default {
   name: 'export',
-  summary: 'Export a factory as an Agent Skill folder (SKILL.md plus the factory).',
   usage: `Usage: factoryhub export <factory> --as skill [--out dir] [--id id] [--force]
 
 Writes <dir>/<id>/SKILL.md and <dir>/<id>/factory/, following

package/packages/cli/src/commands/get.mjs

@@ -6,7 +6,6 @@ import { HUB_NOTE } from './search.mjs';
 
 export default {
   name: 'get',
-  summary: 'Download a published factory from factoryhub into a folder, checking every file.',
   usage: `Usage: factoryhub get <id> [--out dir] [--base-url url] [--force]
 
 Downloads the factory's transfer bundle, checks every file against its

package/packages/cli/src/commands/inspect.mjs

@@ -2,7 +2,6 @@ import { engine, readFactory, summarize, out, json, table, plural, styles, usage
 
 export default {
   name: 'inspect',
-  summary: 'Show what a factory does: inputs, steps in order, agents, tools, checks.',
   usage: `Usage: factoryhub inspect <factory> [--json]
 
 Prints a factory's inputs, its steps stage by stage (steps in one stage can

package/packages/cli/src/commands/list.mjs

@@ -3,7 +3,6 @@ import { readFolder, listFactoryDirs, summarize, matches, out, json, table, HOUS
 
 export default {
   name: 'list',
-  summary: 'List the house factories, or the factory folders in a directory.',
   usage: `Usage: factoryhub list [directory] [--query words] [--json]
 
 Lists the factory folders directly inside a directory. With no directory,
@@ -15,11 +14,7 @@ Options:
   options: { boolean: ['json'], string: ['query'] },
   async run({ positional, flags }, io) {
     const dir = positional[0] ? resolve(io.cwd, positional[0]) : HOUSE_FACTORIES;
-    const entries = [];
-    for (const id of await listFactoryDirs(dir)) {
-      const { files } = await readFolder(resolve(dir, id));
-      entries.push(await summarize(files, { id }));
-    }
+    const entries = await Promise.all((await listFactoryDirs(dir)).map(async (id) => summarize((await readFolder(resolve(dir, id))).files, { id })));
     const kept = entries.filter((entry) => matches(entry, flags.query));
     if (flags.json) { json(io, kept); return 0; }
     if (!kept.length) { out(io, entries.length ? 'No factory matches.' : `No factory folders in ${dir}.`); return 0; }

package/packages/cli/src/commands/login.mjs

@@ -0,0 +1,161 @@
+import { hostname } from 'node:os';
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
+import { out, err, json, styles, usage, connect, day, BASE_URL_HELP } from '../util.mjs';
+import { hubClient, deviceLogin, SCOPES, OPT_IN_SCOPES, TOKEN_PATTERN } from '../../../engine/lib/hub.mjs';
+import { saveCredential, storedCredential, credentialsPath, TOKEN_ENV, PRIVACY } from '../../../engine/lib/credentials.mjs';
+
+const MAX_DAYS = 366;
+
+/** Scopes from --scopes "a,b" or "a b": each one known, none repeated. */
+export function parseScopes(value) {
+  if (value === undefined) return null;
+  const scopes = [...new Set(String(value).split(/[\s,]+/).filter(Boolean))];
+  if (!scopes.length) throw usage(`--scopes needs at least one of: ${SCOPES.join(', ')}.`);
+  const unknown = scopes.filter((scope) => !SCOPES.includes(scope));
+  if (unknown.length) throw usage(`Unknown scope ${unknown.join(', ')}. Choose from: ${SCOPES.join(', ')}.`);
+  return SCOPES.filter((scope) => scopes.includes(scope));
+}
+
+function parseDays(value) {
+  if (value === undefined) return null;
+  const days = Number(value);
+  if (!Number.isInteger(days) || days < 1 || days > MAX_DAYS) throw usage(`--days needs a whole number from 1 to ${MAX_DAYS}, not "${value}".`);
+  return days;
+}
+
+/** Reads a token without showing it: hidden typing at a terminal, else all of stdin. */
+export async function readSecret(io, prompt) {
+  if (io.stdin.isTTY) {
+    io.stderr.write(prompt);
+    const muted = new Writable({ write(_chunk, _encoding, done) { done(); } });
+    const reader = createInterface({ input: io.stdin, output: muted, terminal: true });
+    try {
+      const line = await new Promise((resolve) => { reader.once('line', resolve); reader.once('close', () => resolve('')); });
+      io.stderr.write('\n');
+      return line.trim();
+    } finally { reader.close(); }
+  }
+  let text = '';
+  for await (const chunk of io.stdin) text += chunk;
+  return text.trim();
+}
+
+const shortName = () => `factoryhub CLI on ${hostname() || 'this computer'}`.slice(0, 60);
+const prefixOf = (token) => (token?.prefix ? `${token.prefix}…` : 'fhpat_…');
+
+/** What the person sees once a token is stored. */
+function report(io, { base, me, path, flags, replaced, origin }) {
+  const s = styles(io);
+  if (flags.json) {
+    json(io, { base, account: { handle: me.account.handle, name: me.account.name }, token: { id: me.token.id, name: me.token.name, prefix: me.token.prefix, scopes: me.token.scopes, expires: me.token.expires, origin }, saved: path, replaced });
+    return;
+  }
+  out(io, `${s.green('Logged in')} to ${base} as ${s.bold(`@${me.account.handle}`)}.`);
+  out(io, `  Token    ${me.token.name} (${prefixOf(me.token)}), expires ${day(me.token.expires)}`);
+  out(io, `  Scopes   ${me.token.scopes.join(', ')}`);
+  out(io, `  Saved in ${path}, ${PRIVACY}.`);
+  if (replaced === 'revoked') out(io, s.dim('  The token this computer received by its previous login was revoked.'));
+  else if (replaced === 'kept') out(io, s.dim('  The token saved before was one you passed in, so it was not revoked: revoke it in your account settings if nothing else uses it.'));
+  else if (replaced === 'not_revoked') out(io, s.yellow('  The token this computer received by its previous login could not be revoked: revoke it in your account settings.'));
+  out(io, `\nNext: ${s.bold('factoryhub push <folder>')} saves a factory to your account, privately.`);
+  if (!me.token.scopes.includes('factories:publish')) out(io, s.dim('To publish factories from here, log in with --scopes including factories:publish.'));
+  if (io.env[TOKEN_ENV]) err(io, s.yellow(`\nFACTORYHUB_TOKEN is set, so it is used instead of this login until you unset it.`));
+}
+
+// After a new token is stored, the one it replaced is revoked only if this
+// CLI received it by device login: it was never printed, so nothing else
+// should be using it. A token the person passed in with --token may also live
+// in CI or another machine, so it is left alone. A record without an origin
+// predates this rule and is treated as passed in.
+// Returns 'revoked', 'not_revoked', 'kept' or null when nothing was replaced.
+async function revokeReplaced(base, previous, io) {
+  if (!previous?.token) return null;
+  if (previous.origin !== 'device') return 'kept';
+  try {
+    await hubClient({ baseUrl: base, env: io.env, fetchImpl: io.fetch, token: previous.token }).revoke();
+    return 'revoked';
+  } catch {
+    return 'not_revoked';
+  }
+}
+
+export default {
+  name: 'login',
+  usage: `Usage: factoryhub login [--scopes a,b] [--name text] [--days n] [--no-browser]
+       factoryhub login --token < token.txt
+
+Shows a short code and opens the factoryhub device page. Sign in there,
+check the code matches, choose what this computer may do, and approve.
+The token it receives is saved in ${'${XDG_CONFIG_HOME:-~/.config}'}/factoryhub/credentials.json,
+readable only by you on macOS and Linux (mode 0600; on Windows, as private
+as your user folder). It is never printed. A later login revokes a token an
+earlier device login saved, but never one you passed in with --token.
+
+Scopes (default: every scope that is not opt-in):
+  factories:read     open your private factories
+  factories:write    save factories to your account (push)
+  runs:start         start hosted runs
+  runs:read          follow your runs and read their results
+  factories:publish  publish factories (opt-in: tick it on the page)
+  runs:decide        decide a waiting step for you (opt-in: tick it on the page)
+
+For CI or a machine without a browser, make a token in your account
+settings and pass it on standard input with --token, or set FACTORYHUB_TOKEN
+(which always wins over a saved login).
+
+Options:
+  --scopes      the scopes to ask for, comma-separated
+  --name        what the token is called on your account page
+                (default: "factoryhub CLI on <this computer>")
+  --days        how long the token lives, 1 to ${MAX_DAYS} days (default: the hub's, 90)
+  --no-browser  print the address instead of opening it
+  --token       read a token from standard input instead
+  --base-url    ${BASE_URL_HELP}
+  --json        print the result as JSON`,
+  options: { boolean: ['token', 'browser', 'json'], string: ['scopes', 'name', 'days', 'base-url'] },
+  async run({ positional, flags }, io) {
+    if (positional.length) throw usage(`login takes no words, only options. To pass a token, use: factoryhub login --token < token.txt`);
+    const { base, hub } = await connect(flags, io);
+    const s = styles(io);
+    const scopes = parseScopes(flags.scopes);
+    const days = parseDays(flags.days);
+    const name = flags.name === undefined ? shortName() : String(flags.name).trim().slice(0, 60);
+    if (!name) throw usage('--name cannot be empty.');
+    const previous = await storedCredential(base, io.env);
+
+    let token;
+    let origin;
+    if (flags.token) {
+      if (flags.scopes || flags.days || flags.name) throw usage('--token uses the token as it was made; --scopes, --days and --name apply to a new login only.');
+      token = await readSecret(io, 'Paste your factoryhub token (it is not shown) and press Enter: ');
+      if (!token) throw usage('No token on standard input. Pass it like this: factoryhub login --token < token.txt');
+      if (!TOKEN_PATTERN.test(token)) throw usage('That is not a factoryhub personal access token: they start with fhpat_ and are 49 characters long.');
+      origin = 'pasted';
+    } else {
+      const asked = scopes || [];
+      const optIn = asked.filter((scope) => OPT_IN_SCOPES.includes(scope));
+      const answer = await deviceLogin(hub, {
+        name, scopes, days,
+        sleep: io.sleep,
+        onCode: async ({ userCode, verificationUri, verificationUriComplete, expiresIn }) => {
+          err(io, `To log in to ${base}, open this page in a browser where you are signed in:\n\n  ${s.bold(verificationUri)}\n\nand enter the code  ${s.bold(userCode)}\n`);
+          err(io, s.dim(`Check that the page shows the same code before you approve.${optIn.length ? ` Tick ${optIn.join(' and ')} there: opt-in scopes are granted only when you tick them.` : ''}`));
+          const page = verificationUriComplete || verificationUri;
+          if (flags.browser !== false && io.openUrl && new URL(page, base).origin === new URL(base).origin) {
+            if (await io.openUrl(new URL(page, base).href)) err(io, s.dim('Opened the page in your browser.'));
+          }
+          err(io, `Waiting for you to approve (the code works for ${Math.round(expiresIn / 60)} minutes; Ctrl+C to stop)...`);
+        },
+      });
+      token = answer.access_token;
+      origin = 'device';
+    }
+
+    const me = await hubClient({ baseUrl: base, env: io.env, fetchImpl: io.fetch, token }).me();
+    const path = await saveCredential(base, { token, origin, id: me.token.id, name: me.token.name, prefix: me.token.prefix, scopes: me.token.scopes, expires: me.token.expires, account: me.account.handle }, io.env);
+    const replaced = previous && previous.token !== token ? await revokeReplaced(base, previous, io) : null;
+    report(io, { base, me, path: credentialsPath(io.env) || path, flags, replaced, origin });
+    return 0;
+  },
+};

package/packages/cli/src/commands/logout.mjs

@@ -0,0 +1,43 @@
+import { out, styles, usage, hubBase, BASE_URL_HELP } from '../util.mjs';
+import { hubClient } from '../../../engine/lib/hub.mjs';
+import { storedCredential, deleteCredential, credentialsPath, TOKEN_ENV } from '../../../engine/lib/credentials.mjs';
+
+export default {
+  name: 'logout',
+  usage: `Usage: factoryhub logout [--base-url url]
+
+Revokes the token "factoryhub login" saved, on the factoryhub server first,
+so it stops working everywhere, and then deletes it from this computer. If
+the server cannot be reached, nothing is deleted: run it again later, or
+revoke the token in your account settings.
+
+A token in FACTORYHUB_TOKEN is not touched: unset it yourself, and revoke it
+in your account settings if nobody needs it.
+
+Options:
+  --base-url  ${BASE_URL_HELP}`,
+  options: { string: ['base-url'] },
+  async run({ positional, flags }, io) {
+    if (positional.length) throw usage('logout takes no words, only options.');
+    const s = styles(io);
+    const base = hubBase(flags, io);
+    const stored = await storedCredential(base, io.env);
+    const envNote = io.env[TOKEN_ENV] ? s.yellow(`\nFACTORYHUB_TOKEN is still set, so commands still use that token. Unset it, and revoke it in your account settings if nobody needs it.`) : '';
+    if (!stored) {
+      out(io, `Not logged in to ${base} on this computer: nothing to do.${envNote}`);
+      return 0;
+    }
+    let note;
+    try {
+      await hubClient({ baseUrl: base, env: io.env, fetchImpl: io.fetch, token: stored.token, tokenSource: 'file' }).revoke();
+      note = 'revoked on the server';
+    } catch (error) {
+      // A token the server no longer accepts is already as good as revoked.
+      if (error.status === 401) note = 'the server no longer accepted it';
+      else throw new Error(`${error.message}\nThe token was not revoked, so it is still saved in ${credentialsPath(io.env)}. Try again, or revoke "${stored.name || 'it'}" in your account settings.`, { cause: error });
+    }
+    await deleteCredential(base, io.env);
+    out(io, `${s.green('Logged out')} of ${base}: ${stored.name ? `"${stored.name}" ` : ''}${note}, and deleted from this computer.${envNote}`);
+    return 0;
+  },
+};

package/packages/cli/src/commands/mcp.mjs

@@ -6,7 +6,6 @@
 
 export default {
   name: 'mcp',
-  summary: 'Start the local MCP server on stdio, for MCP clients.',
   usage: `Usage: factoryhub mcp
 
 Starts the factoryhub MCP server on stdin and stdout, the same server as the

package/packages/cli/src/commands/new.mjs

@@ -115,7 +115,6 @@ and run it with your own model key with \`factoryhub run .\`.
 
 export default {
   name: 'new',
-  summary: 'Create a new factory folder that validates and runs.',
   usage: `Usage: factoryhub new <name> [--dir parent] [--title text] [--description text]
 
 Creates <parent>/<name>/ with factory.yaml, flow.yaml, two agents and a README.

package/packages/cli/src/commands/pack.mjs

@@ -40,7 +40,6 @@ The runner stops at every approval step and asks you. With nobody at the keyboar
 
 export default {
   name: 'pack',
-  summary: 'Pack a factory into a zip that runs anywhere with Node, or a bundle .json.',
   usage: `Usage: factoryhub pack <factory> [--out file] [--format zip|json] [--no-runner]
 
 zip (the default) writes <name>/ with the factory's files, the generated