Primary reader → plan → your Approve & build → Coder writes → Compile → Review → preview links.
Agent error queue—
Agent Guide
How to use the Project Agent effectively — phrases, gates, swarm vs edits, Media Studio, and the documentation contract
What the Agent is
The Project Agent is a Cursor-style operator for one factory project at a time. Your chat is private to your account. It works on the real on-disk workspace under ~/aifactory-projects/….
It can read and explain code, stage edits for your Accept, hand large work to the build swarm, launch real previews, sync GitHub, generate images/video (Media Studio), run terminals, and maintain the project’s Brain · Heart · Fingers · AGENTS documentation contract.
It will not invent Cloudflare URLs, production deploys, or pull requests. If a link or status isn’t returned by a factory tool, it isn’t real.
See it end-to-end: open the sample project
Factory Showcase(repo factory-showcase)
— Tour, Feature Board, Design tokens, Components, Improve, and Live doctrine pages show how the factory builds Rust apps.
Every project runs on this contract. The agent must search before write and never leave two files serving the same role under different names.
Layer
Holds
Rule
Brain
What the system is — architecture, maps, models, APIs, stack, charter
Singular, shared, relatively stable
Heart
How it moves — rules, acceptance, sprint, deps, risks, velocity log
Singular, shared, constantly updated
Fingers
What you are doing — current work, interface-in/out, notes
One per person — never merge across people
AGENTS.md
How AIs must behave — conventions, forbidden actions
Fourth artifact — never fold into the three
Paste BRDs/meeting notes with fold this into the contract:. Manage layers anytime on Feature Board → Documentation Contract.
Media Studio
Active (Architecture → Media Studio) — image/video tools live; picture asks short-circuit to FLUX even if the coder LLM is down.
Inactive — agent checks status and tells you to enable Media Studio; it will not fake image URLs.
Vision (looking at screenshots) needs the vision stack up — watch the banner in the composer.
GitHub
Allowed: clone into the factory, link remotes, pull, push, publish a new repo for the project.
Refused: open PRs, deploy to production/K8s, invent prod/PR links.
Use write-capable mode (or the GitHub tab) for mutating git actions.
Phrase cheat sheet
You say
What happens
“How does auth work?”
Architect + real files → path-cited explanation
“Survey / report this — do not modify anything”
Read-only Architect report — no Approve & build, no file writes
“Is it live? What’s the URL?”
Status / public links — real URLs only
“What changed in v0.8.1?”
Version history
“Fix the hardcoded bind address”
Coder stages diffs → you Accept
“Go ahead and build the decision engine”
Change-set → Approve & build → swarm
“Make & deploy” / “go live”
Exact local + Cloudflare links
“Generate a picture of a blue heron”
FLUX (Media Studio)
“Add a business rule: …”
Heart update, deduped
“Fold this into the contract:” + paste
Split into Brain / Heart / Fingers / AGENTS
“Push to GitHub”
github_push / github_publish
Drop a screenshot + “what’s wrong?”
Vision + explain/fix
Hard rules the Agent obeys
Never invent trycloudflare / public URLs — only tool/status output
Survey / “don’t modify” / report-only asks never open Approve & build or write files
Never claim it can’t see on-disk source — primer + tools
Never merge Fingers across people
Never merge AGENTS into Brain/Heart
Never start the swarm without Approve & build
Never write edits to disk without your Accept on staged diffs
Prefer the smallest edit mode that still solves the request
Prefer factory queue_change / go_live over Docker folklore or fake deploys
Practice loop (do this once)
Open Agent, pick a project with a disk workspace.
Ask: “Show build status and the exact live URLs.”
Ask a code question: “How does this project start?”
Try a tiny edit in Coder/Auto, Accept the staged diff in This turn.
Try “go ahead and build …” for something larger — Approve & build on the card.
Add a Heart rule: “add a business rule: …”
When ready for share preview: “go live” — only trust the URLs it returns.
One-line summary: private per-user Cursor-style agent for one factory project — real files, staged Accept edits, swarm handoff, real previews, GitHub sync, Media Studio, and mandatory Brain/Heart/Fingers/AGENTS — never invented links or duplicate docs.
Agents Lab
Drag-and-drop agent architecture · Recovery lane (Kimi) · Prompt modes & how to optimize them
AI configuration — drag & drop
Loading providers into Architect / Coder / Reviewer / Recovery…
Runtime architecture
How a turn flows. Kimi is Recovery only — it never runs the Reviewer / quality gate.
Youquestion / edit ask
→
Autopick Architect / Coder / Reviewer
→
Toolsread · search · stage · swarm
→
AnswerSituation-first markdown
⇢
RecoveryKimi unsticks empty / hang / vague
Approve & build swarm: Architect → Coder → Compile → Reviewer (local)Kimi is not in this chain.
Prompt modes the agent can handle
Optimize your asks
Each mode activates different system rules, primer depth, and tools. Click a mode for requirements and optimization tips.
Progress Dashboard
Active builds, version metrics, and pipeline status — double-click a project to open its dashboard
—PDF compliance
Project Library
Compiled apps ready to open in your browser.
AI Software Factory — Access Links
Open or copy the portal's public Cloudflare link plus local and LAN addresses.
Currently Working On
Next Project Request
Request Queue
8-Stage Pipeline
Project Library
All applications produced by the factory — completion % based on each project's feature list
Pull from any GitHub link
Paste https://github.com/owner/repo, owner/repo, or a git URL. Clones into ~/aifactory-projects and adds it here. Connect a token on the GitHub tab for private repos.
Project
Request Portal
Prefer Agent → + New project for Cursor-style PLAN.md → Approve & build. This intake still creates projects and hands them off to Agent.
What Greenfield Intake does
Greenfield Intake creates a brand-new app workspace from plain English, then opens Agent to write PLAN.md, run Approve & build, and return Cloudflare / local preview links.
Planning Chat — sketch scope before you commit.
New Project — creates the project, then hands off to Agent (same path as Agent → + New project).
Existing project tabs — feature requests on apps already in the factory.
For day-to-day building, stay in Agent — Swarm tab shows Architect (primary reader) → Coder → approval. Secrets should not go in the description.
Creates the workspace, then opens Agent for PLAN.md → Approve & build → tunnel links. Secrets and API keys should not go in the description.
Select a project
Codebase Ingestion
Drag a whole folder in to index it — then ask a local model anything about that codebase. Every ingested project gets its own tab.
📁
Drag & drop a project folder here
or click to choose a folder — source files are read locally, binaries & node_modules/.git are skipped
Ask about this codebase
Local model answers grounded in the ingested source
Component Library
One catalog · face:
No verified components yet. After CI passes, admins can extract reusable pieces into this catalog.
Version Control
Local git snapshots for factory workspaces. Canonical hosting & PRs live in Forgejo.
Deployment Manager
Store Beeks, AWS, and SSH credentials + connection strings for shipping projects to remote servers. Secrets stay on the factory host (chmod 600) and are masked in the UI.
New deployment target
Admins can save credentials. Blank secret fields keep the existing value.
Security tokens
Connection strings
Targets
Loading…
Bind project → target
Choose which remote target a Built Project should use when you deploy from the factory.
GitHub
Connect an account, pull repos into the factory, and push local work back upstream.
Pull project from GitHub
Clones into ~/aifactory-projects and registers it in Project Library.
Connect a token first for private repos. To check in a factory project that has no remote yet, open the project’s GitHub sync card and use Create on GitHub & push.
Create empty GitHub repo
Creates a repository on the connected account (no local files). Then clone it here, or link it from a factory project and push.
Personal Access Token
Create a token at
github.com/settings/tokens
with repo scope (or fine-grained Contents: Read/Write on the repos you need), then paste it here.
Sign in with GitHub
Optional OAuth App flow. Configure client id/secret on the factory host
(admin setup docs — not shown here). Callback
/api/github/oauth/callback.
Brain · Heart · Fingers · AGENTS — search before write, consolidate never duplicate
Designer Canvas
Figma-like artboard — tokens, components, and specs publish into Brain + designer fingers
100%
Import brand guide
Paste brand copy or a style guide — colors and voice are extracted into the canvas.
Staging & Rollback
Builds auto-deploy — use this panel to preview any version and roll back
Build History
Each auto-shipped build includes notes and changed files. Double-click a build or file to open the code review dashboard.
CI/CD Pipeline
Admin-only trigger. Canonical CI lives in Woodpecker — this panel is a thin factory status view, not a second CI product.
LangFuse Observability
Agent traces and pipeline observability
Support & Ticket Management
Raise support requests, track work, and reply on a shared thread — updates email the requester and the support team. Drag cards between lanes to change status.
Collaborative Kanban Board
A shared board for the whole team — drag cards between lanes. Changes sync live for everyone signed in.
User Access
Approve who can sign in to the factory
Pending approval 0
Active members
Remote Desktop
Admin-only full control of this machine (screen + mouse + keyboard) through the portal.
Remote desktop
Admin only. Backends listen on localhost; this tab is the only ingress.
Viewer idle
Click Start, then Connect to control this desktop.
Telephone
Send SMS through an Android phone on USB‑C (ADB). Requires USB debugging once.
Checking phone…
SMS Gateway API (phone → HTTP)
Install open-source SMSGate on the phone so it becomes a local SMS API.
The portal tunnels that API over USB‑C (adb reverse) — no Wi‑Fi required.
Plug in the phone (USB debugging allowed) and tap Install SMS Gateway API.
On the phone: open the app → enable Local Server → grant SMS (and notifications if asked).
Copy the username/password shown under Local Server into the fields above → Save credentials.
Tap Start USB tunnel — status should show the API live on this PC.
Compose SMS
Messages go out on the phone’s SIM over the carrier — not through this PC’s network.
0 / 1600
Outbox
Recent sends from this portal (stored on the factory host).
Phone setup
Use a data-capable USB‑C cable (charge-only cables will not show up in ADB).
On the phone: Settings → About phone → tap Build number 7×, then enable USB debugging.
Plug in → set USB mode to File Transfer / MTP → unlock → tap Allow on the RSA prompt.
Prefer the SMS Gateway API card above (phone becomes an HTTP SMS API over USB).
Host one-liner: sudo ./scripts/setup-telephone.sh
Process Control
Identify and kill AI-factory processes, with a running history of factory activity
Email notifications
SMTP delivery status and a manual test send.
to
Backups
Portable .tar.gz snapshots of the factory (portal source + config/data). Schedule automatic backups, then download or delete existing ones.
Live processes
The portal, tunnels, model servers, builds, and live previews. Model servers and the portal itself are protected.
Activity history
A persistent log of process kills, model mode switches, auto-recovery, and boots.
Factory Self-Build
The factory modifies its own source on a safe staging copy, compiles + runtime-verifies it, then redeploys itself on your approval
Describe a change to the factory
Plain English. Edits happen on a copy and are compiled + runtime-verified before anything touches the live portal.
Build steps
Error Feedback Loop
Runtime errors from deployed apps become fix cards — diagnosed and auto-resolved through the full build pipeline until clean.
How it works
When a live app crashes or logs an error, a card appears here. The AI diagnoses it and auto-starts resolution — change build, compile repair, and the quality loop until the build is clean. If it was live, the app is relaunched and verified. Factory errors still need manual accept (staged self-build). Stream errors via POST /api/errors/report.
Architecture
Live hardware, model swarm, and how Approve & build runs Architect → Coder → Compile → Review. Agent Recovery (Kimi) lives under Agent → Agents Lab.
AI configuration — drag & drop
Loading Architect / Coder / Reviewer providers…
Serving modes
Within the Build Swarm profile — choose how the three RTX GPUs serve coding models.
How the swarm builds code
From your request to a running preview — each step and whether its health gate is ready right now.
System overview
Engine
GPU card temperatures · live builds · stuck/fail actions · system restore points
Card temperatures
Pending change-sets
Factory plans waiting for Approve & build — same gate as the Agent card.
Currently building
Past attempts that failed or needed help
System restore points
Git-backed checkpoints from builds, retries, and aborts. Restore puts the workspace back to that snapshot.
Resources
Live server load & thermals · refreshes every few seconds
GPUs
⚠ Emergency controls
Use if temperatures spike. Stopping the AI models drops GPU load immediately so the cards cool down.
Startup & Services
Live status of every process the factory starts on boot
AI swarm self-test
Sends a live generation probe to each build model (architect → coder → reviewer) and confirms it actually produces output.
Release Notes
Auto-generated by Docs Agent in plain English
💬Chat0▴
Your account
Password change required
An administrator set a temporary password. Choose a new password before continuing.
Email
Needed for password-reset emails. Only you (or an admin) can change this.
Reset via email
Send a one-time reset link to your email (expires in 1 hour). You can also use Forgot password? on the sign-in screen.
Change password now
You’ll be signed out after a successful change.
Open a ticket
Raise a support request from any page. Attach a screenshot if it helps.