Platform Documentation

Getting Started

New to Forge? Here's the shortest path from sign-in to your first AI-generated test. If you're a workspace user, the in-app sidebar tour walks you through these same steps the first time you log in — you can always restart it from the user menu in the bottom-left.

1. Create your first project

Open Projects in the sidebar and click New Project. Give it a short name (e.g. the design or test campaign) and an optional description, then press Enter or click Create Project. Each project owns its own files, chat history, and task list.

2. Upload your design files

Inside the project, drag GDS / SDS files (or any reference docs) into the left panel. Files are stored per-project and become available to the AI agent immediately.

3. Ask the agent to generate a test

Use the chat panel to describe what you want to test in plain language. The agent proposes a task, runs synthesis, and stages it for execution. Tasks then move through queued → executing → needs review → completed. See the AI Agent and Task Workflow sections for the full lifecycle.

4. Watch progress on the Dashboard

The Dashboard surfaces stuck tasks, per-project health, and weekly completion trends. The cross-project Tasks page lets you filter, sort, and drill into any individual run.

Overview

Forge is a collaborative workspace for semiconductor design teams. It combines project organisation, an AI agent that synthesises test code from natural-language descriptions, file storage for design documents, and a full test-execution tracking pipeline — from initial task staging through physical hardware execution to results analytics.

• ▸Multi-workspace — switch between isolated team environments
• ▸Role-based access — Admin, User, Observer, Technician
• ▸AI-driven synthesis — describe tests in plain language, get production code
• ▸End-to-end tracking — staged → queued → executing → completed
• ▸Real-time streaming — agent responses and tool calls streamed live via SSE

Dashboard

The dashboard gives a high-level view of workspace health at a glance.

Metric Cards

• ▸Active Tests — count of tasks in staged, queued, synthesizing, needs_review, and execute states; includes an "awaiting review" sub-count
• ▸Success Rate — completed ÷ (completed + failed), shown as a percentage
• ▸Projects — total project count and aggregate task count

Weekly Analytics Chart

An 8-week area chart showing Tests Submitted and Tests Completed per week, aligned to Monday boundaries. Data is cached for 60 seconds and refreshed silently in the background so switching tabs does not cause a reload flash.

Projects

Projects are the top-level containers for test campaigns. Each project holds its own file store, chat history, and task list.

Projects List

• ▸Create — name + optional description; Enter key submits
• ▸Rename — click the pencil icon on any project card
• ▸Delete — admin-only; cascades to tasks, files, and chat history with a confirmation warning
• ▸Card layout — responsive 1 → 2 → 3 column grid with hover action buttons

Project Detail — Two-Panel View

Opening a project splits the screen into two resizable panels:

• ▸Left panel — Chat & Upload — AI chat interface with drag-and-drop file upload
• ▸Right panel — Files & Tasks — file browser with preview and the project task list

Tasks

Tasks represent individual test items — from AI-synthesised code generation jobs to physical execution runs. The Tasks page provides a cross-project view of every task in the workspace.

Task List

• ▸Columns — task name, project, status, priority, assigned user, created date
• ▸Filter by status — any single status or show all
• ▸Search — filter by task name substring
• ▸Sort — click column headers

Task Detail Modal

• ▸Description — full task description and metadata
• ▸Report — AI-generated markdown output rendered with tables, lists, and code blocks
• ▸Assets — generated source files and result files with preview and download
• ▸Metrics — pass/fail indicators when quantitative results are available

Status Badges

File Management

Each project has its own file store backed by Google Cloud Storage. Files are accessible to the AI agent and visible in the right-panel file browser.

Upload

• ▸Drag-and-drop or click — in the left panel upload zone
• ▸Max size — 200 MB per file
• ▸Supported types — GDS, SDS, PDF, MD, TXT, CSV, JSON, DOC, DOCX, XLS, XLSX, PNG, JPG, SVG, PY, TS, JS, ZIP, TAR, GZ
• ▸MANIFEST.md — auto-generated after each upload so the AI agent knows what files exist

File Preview

• ▸Images — rendered inline in the browser
• ▸Text / Code / Markdown / CSV / JSON — full text view
• ▸PDF / DOCX / XLSX — text extracted and displayed
• ▸GDS / SDS (binary) — hex preview

AI Agent

The AI agent lives in the project chat panel. Describe what you want to test in plain language; the agent reads your design files, reasons over them, and proposes structured test tasks.

Agent Capabilities

• ▸File comprehension — reads and extracts content from uploaded design documents, datasheets, and spec files
• ▸Task awareness — queries existing tasks in the project to avoid duplicates and build on prior work
• ▸Test task proposals — generates structured, reviewable batches of test tasks based on your specifications
• ▸Task creation — commits approved tasks directly into the project pipeline

Task Proposal Flow

When the agent proposes tasks, a review card appears in chat showing each proposed task (title, description, priority). You can Approve to create all tasks, or Reject to discard and refine the prompt. Approved tasks enter the pipeline at staged status.

Streaming

Chat responses are streamed in real time so you can follow the agent's reasoning step by step.

Task Workflow

Every task moves through a defined lifecycle from creation to completion.

• ▸staged — task created, awaiting submission
• ▸queued — submitted to synthesis pipeline, waiting for a worker
• ▸synthesizing — AI code generation in progress
• ▸needs_review — awaiting engineer or technician intervention
• ▸ready — synthesis complete, queued for physical test execution
• ▸executing — running on physical hardware
• ▸completed — test finished successfully
• ▸failed — unrecoverable error; inspect logs for details
• ▸cancelled — stopped by an admin or technician

Phases

• ▸synthesis — task is in the AI code-generation pipeline
• ▸execution — task is in the hardware execution pipeline
• ▸(none) — task is staged and not yet in any pipeline

Notifications

• ▸Toast notifications — slide in from the top-right for success, error, and info events; auto-dismiss after 6 seconds
• ▸Task status watcher — polls task status in the background and fires a notification on every state transition
• ▸Manual dismiss — click the × on any notification to remove it immediately

Administration

The Admin panel is restricted to workspace administrators and covers member management, workspace settings, and a task overview.

Members

• ▸Invite — add a member by email and assign a role
• ▸Change role — inline dropdown per member row (Admin, User, Observer, Technician)
• ▸Remove — delete button removes the member from the workspace
• ▸Task count — shown per member for quick capacity assessment

Workspace Settings

• ▸Task limit — maximum active tasks per user (1–500); enforced at task creation
• ▸Create workspace — create a new isolated workspace; you become its admin automatically and can invite others

Task Overview Table

A read-only table of all tasks in the workspace showing task name, project, assigned user, status, and priority — useful for ops review without navigating per-project.

Integrations

Forge supports two optional integrations that change how generated code and tasks are tracked. Both are workspace-scoped, toggled by an admin, and require the workspace to be on the Professional tier. New projects and tasks created while an integration is on will use it; existing ones keep behaving as they did at creation.

GitHub

With GitHub on, every new project provisions a private GitHub repo, and the coding agent commits its synthesis output as a branch and opens a Pull Request against the repo. Without GitHub, source code lives in Forge-managed storage as before. Build artifacts, run logs, and executor binaries continue to live in Forge storage in either mode — GitHub is for the source code only.

Connecting

1. Open Admin from the sidebar (admins only). The right-hand column has a GitHub Integration card.
2. Click Connect GitHub. You will be sent to GitHub to install the Forge App on your account, accept the requested permissions, and authorize.
3. GitHub redirects you back to Forge. The card now shows your GitHub username, account type, and the connection date.
4. Tick Enable for new projects. From this point on, every new project you create gets a fresh private repo named automatically.

What happens behind the scenes

• ▸Project creation — a new private repo is created on your GitHub account, named after the project. Repo metadata is stored on the project row.
• ▸Task synthesis — when a task runs, the coding agent clones the repo, commits its output to a fresh branch, and opens a Pull Request you can review.
• ▸PR re-runs — re-running an in-flight task pushes additional commits to the same branch; merged or closed PRs trigger a new branch on the next run.
• ▸Webhook sync — when you merge or close a PR on GitHub, the linked task status is updated automatically. Uninstalling the app on GitHub clears the workspace connection.

Disconnecting

The Disconnect button uninstalls the Forge App from your GitHub account and clears the integration on Forge in one step. Existing repos and PRs are left untouched. New projects created afterwards will fall back to Forge-managed storage.

Linear

With Linear on, every new task automatically creates a corresponding Linear issue under your team. If GitHub is also enabled, Linear's native GitHub integration auto-links each Pull Request to its issue, so the issue moves through Todo → In Progress → In Review → Done as the PR progresses — no manual updates needed.

Connecting

1. On linear.app open Settings → API → Personal API keys and create a key. Copy it; you will not see it again.
2. In Forge, open Admin → the Linear Integration card. Paste the key into the field and click Connect Linear.
3. Forge fetches the teams visible to your key. Pick the team that should hold new issues and click Use this team.
4. Tick Enable for new tasks. Every task the AI agent creates from this point on will land in your Linear team as an issue.
5. One-time on Linear: linear.app → Settings → Integrations → GitHub, and connect the GitHub account that hosts your project repos. This is what lets Linear pick up Pull Requests and back-link them to issues automatically.

What happens behind the scenes

• ▸Task creation — when the AI agent proposes tasks in chat, each one is created as a Linear issue under the selected team and the issue identifier is saved on the task.
• ▸PR auto-link — with both integrations on, the coding agent embeds the Linear identifier in PR branch names so Linear attaches the PR to the issue and walks it through statuses.
• ▸Failure tolerance — if Linear is unreachable, task creation still succeeds locally — only the issue link is missing, and a re-run can backfill it.

Disconnecting

Disconnect clears the API key and team selection on Forge so new tasks stop creating Linear issues. The key itself is not revoked on Linear — if you want to fully revoke access, delete the key on linear.app under Settings → API.

Roles & Permissions

Multi-Workspace Support

A single Forge account can belong to multiple workspaces. Use the workspace switcher in the sidebar header to toggle between them — all data (projects, tasks, files, members) is fully isolated per workspace. Creating a new workspace from the Admin panel makes you its admin; you can then invite teammates by email.