singularity-forge/docs/user-docs/getting-started.md

# Getting Started with SF

SF is a purpose-to-software compiler. It turns bounded intent into PDD contracts, researches missing context, writes failing tests or executable evidence first, implements the smallest satisfying change, verifies, and records what happened. This guide walks you through installing and running SF on Linux.

---

## Prerequisites

| Requirement | Minimum | Recommended |
|-------------|---------|-------------|
| **[Node.js](https://nodejs.org/)** | 26.1.0 | 26.1+ |
| **[Git](https://git-scm.com/)** | 2.20+ | Latest |
| **LLM API key** | Any supported provider | Anthropic (Claude) |

Don't have Node.js or Git yet? Follow the Linux instructions below.

---

## Install on Linux

> **Downloads:** [Node.js](https://nodejs.org/) | [Git](https://git-scm.com/download/linux) | [nvm](https://github.com/nvm-sh/nvm)

Pick your distro, then follow the steps.

#### Ubuntu / Debian

**Step 1 — Install Node.js and Git:**

```bash
curl -fsSL https://deb.nodesource.com/setup_26.x | sudo -E bash -
sudo apt-get install -y nodejs git
```

#### Fedora / RHEL / CentOS

**Step 1 — Install Node.js and Git:**

```bash
curl -fsSL https://rpm.nodesource.com/setup_26.x | sudo bash -
sudo dnf install -y nodejs git
```

#### Arch Linux

**Step 1 — Install Node.js and Git:**

```bash
sudo pacman -S nodejs npm git
```

#### Using nvm (any distro)

**Step 1 — Install nvm, then Node.js:**

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc   # or ~/.zshrc
nvm install 26
nvm use 26
```

#### All distros: Steps 2-7

**Step 2 — Verify dependencies are installed:**

```bash
node --version   # should print v26.x or higher
git --version    # should print 2.20+
```

**Step 3 — Install SF:**

```bash
npm install -g singularity-forge
```

**Step 4 — Set up your LLM provider:**

```bash
# Option A: Set an environment variable (Anthropic recommended)
export ANTHROPIC_API_KEY="sk-ant-..."

# Option B: Use the built-in config wizard
sf config
```

To persist the key, add the export line to `~/.bashrc` (or `~/.zshrc`):

```bash
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc
```

See [Provider Setup Guide](./providers.md) for all 20+ supported providers.

**Step 5 — Launch SF:**

```bash
cd ~/my-project   # navigate to any project
sf               # start a session
```

**Step 6 — Verify everything works:**

```bash
sf --version     # prints the installed version
```

Inside the session, type `/model` to confirm your LLM is connected.

> **Permission errors on `npm install -g`?** Don't use `sudo npm`. Fix npm's global directory instead:
> ```bash
> mkdir -p ~/.npm-global
> npm config set prefix '~/.npm-global'
> echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
> source ~/.bashrc
> npm install -g singularity-forge
> ```

---

### Docker on Linux

> **Downloads:** [Docker Engine](https://docs.docker.com/engine/install/)

Run SF in an isolated Linux sandbox without installing Node.js on your host.

**Step 1 — Install Docker Engine**.

**Step 2 — Clone the SF repo:**

```bash
git clone https://github.com/singularity-ng/singularity-forge.git
cd singularity-forge/docker
```

**Step 3 — Create and enter a sandbox:**

```bash
docker sandbox create --template . --name sf-sandbox
docker sandbox exec -it sf-sandbox bash
```

**Step 4 — Set your API key and run SF:**

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
sf autonomous "implement the feature described in issue #42"
```

See [Docker Sandbox docs](../../docker/README.md) for full configuration, resource limits, and compose files.

---

## After Installation

### Choose a Model

SF auto-selects a default model after provider setup. Switch anytime inside a session:

```
/model
```

Or configure per-phase models in preferences — see [Configuration](./configuration.md).

---

## Two Ways to Work

### Assisted Mode — `/next`

Type `/next` inside a session. SF executes one unit of work at a time, pausing between each with a wizard showing what completed and what's next.

- **No `.sf/` directory** — starts a discussion flow to capture your project vision
- **Milestone exists, no roadmap** — discuss or research the milestone
- **Roadmap exists, slices pending** — plan the next slice or execute a task
- **Mid-task** — resume where you left off

Assisted mode keeps you in the loop, reviewing output between each step.

### Autonomous Mode — `/autonomous`

Type `/autonomous` and walk away. SF researches, plans, executes, verifies, commits, and advances through every slice until the milestone is complete. `/autonomous` remains available as a short alias.

```
/autonomous
```

See [Autonomous Mode](./autonomous-mode.md) for full details.

---

## Recommended Workflow: Two Terminals

Run autonomous mode in one terminal, steer from another.

**Terminal 1 — let it build:**

```bash
sf
/autonomous
```

**Terminal 2 — steer while it works:**

```bash
sf
/discuss    # talk through architecture decisions
/status     # check progress
/queue      # queue the next milestone
```

Both terminals read and write the same `.sf/` files. Decisions in terminal 2 are picked up at the next phase boundary automatically.

---

## How SF Organizes Work

```
Milestone  →  a shippable version (4-10 slices)
  Slice    →  one demoable vertical capability (1-7 tasks)
    Task   →  one context-window-sized unit of work
```

The iron rule: **a task must fit in one context window.** If it can't, it's two tasks.

All state lives on disk in `.sf/`:

```
.sf/
  PROJECT.md          — what the project is right now
  REQUIREMENTS.md     — requirement contract
  DECISIONS.md        — append-only architectural decisions
  KNOWLEDGE.md        — cross-session rules and patterns
  STATE.md            — quick-glance status
  milestones/
    M001/
      M001-ROADMAP.md — slice plan with dependencies
      slices/
        S01/
          S01-PLAN.md     — task decomposition
          S01-SUMMARY.md  — what happened
```

---

## VS Code Extension

SF is also available as a VS Code extension. Install from the marketplace (publisher: FluxLabs) or search for "SF" in VS Code extensions:

- **`@sf` chat participant** — talk to the agent in VS Code Chat
- **Sidebar dashboard** — connection status, model info, token usage
- **Full command palette** — start/stop agent, switch models, export sessions

The CLI (`singularity-forge`) must be installed first — the extension connects to it via RPC.

---

## Web Interface

SF has a browser-based interface for visual project management:

```bash
sf --web
```

See [Web Interface](./web-interface.md) for details.

---

## Resume a Session

```bash
sf --continue    # or sf -c
```

Resumes the most recent session for the current directory.

Browse all saved sessions:

```bash
sf sessions
```

---

## Updating SF

SF checks for updates every 24 hours and prompts at startup. You can also update manually:

```bash
npm update -g singularity-forge
```

Or from within a session:

```
/update
```

---

## Quick Troubleshooting

| Problem | Fix |
|---------|-----|
| `command not found: sf` | Add npm global bin to PATH |
| `sf` runs `git svn dcommit` | oh-my-zsh conflict — `unalias sf` or use `sf-cli` |
| Permission errors on `npm install -g` | Fix npm prefix (see Linux notes) or use nvm |
| Can't connect to LLM | Check API key with `sf config`, verify network access |
| `sf` hangs on start | Check Node.js version: `node --version` (need 26+) |

For more, see [Troubleshooting](./troubleshooting.md).

---

## Next Steps

- [Autonomous Mode](./autonomous-mode.md) — deep dive into autonomous execution
- [Configuration](./configuration.md) — model selection, timeouts, budgets
- [Commands Reference](./commands.md) — all commands and shortcuts
- [Provider Setup](./providers.md) — detailed setup for every provider
- [Working in Teams](./working-in-teams.md) — multi-developer workflows