# FlyDocs Core

AI-assisted spec-driven development for your codebase. FlyDocs installs skills, workflows, and issue management directly into your project — works with Claude Code and Cursor.

## Install

```bash
npm install -g @flydocs/cli
```

Beta releases:

```bash
npm install -g @flydocs/cli@beta
```

Alpha releases (internal testing):

```bash
npm install -g @flydocs/cli@alpha
```

Requires Node.js >= 18.17.0 and Python 3.8+ (for mechanism scripts).

## Quick Start

```bash
# Install FlyDocs into your project
cd your-project
flydocs

# Open your IDE and run the guided setup
/onboard

# Start working
/start-session
```

### Tiers

| Tier                  | Install                     | Backend                                |
| --------------------- | --------------------------- | -------------------------------------- |
| **Local** (free)      | `flydocs init --tier local` | File-based issues in `flydocs/issues/` |
| **Cloud** (connected) | `flydocs init --tier cloud` | Linear via GraphQL API                 |

`flydocs` runs `init` by default and prompts for tier if `--tier` is omitted. Local tier requires no accounts or API keys. Cloud tier prompts for a FlyDocs API key (`fdk_…`) which is stored at `~/.flydocs/credentials`.

## What Gets Installed

FlyDocs adds workflow infrastructure alongside your code:

| Component     | Location             | Purpose                                                      |
| ------------- | -------------------- | ------------------------------------------------------------ |
| **Skills**    | `.claude/skills/`    | Workflow, issue management, context graph                    |
| **Commands**  | `.claude/commands/`  | Slash commands (`/capture`, `/activate`, `/implement`, etc.) |
| **Agents**    | `.claude/agents/`    | Subagent definitions (PM, Implementation, QE, Research)      |
| **Context**   | `flydocs/context/`   | Project definition and priorities                            |
| **Knowledge** | `flydocs/knowledge/` | Decisions, notes, product docs                               |
| **Config**    | `.flydocs/`          | Templates, hooks, version tracking                           |

## Commands

### CLI

| Command          | Purpose                                       |
| ---------------- | --------------------------------------------- |
| `flydocs`        | Fresh install into current project            |
| `flydocs update` | Update to latest version                      |
| `flydocs stream` | Read the session records written at each wrap |
| `flydocs --help` | Show all options                              |

### IDE (Claude Code / Cursor)

| Command          | Purpose                     |
| ---------------- | --------------------------- |
| `/onboard`       | Guided project onboarding   |
| `/start-session` | Begin a work session        |
| `/capture`       | Create a new issue          |
| `/activate`      | Pick up an issue to work on |
| `/implement`     | Start implementation        |
| `/review`        | Submit for code review      |
| `/wrap-session`  | End session with summary    |

## Updating

```bash
# Update FlyDocs in your project
flydocs update

# Force reinstall at same version
flydocs update --force
```

Updates replace framework files while preserving your project content, config, and issues.

## Guides

| Guide                                                     | For                                             |
| --------------------------------------------------------- | ----------------------------------------------- |
| [Setting up the tool surface](docs/tool-surface-setup.md) | what `init` and `update` write, and why         |
| [Managed permissions](docs/managed-permissions.md)        | permission modes and workspace policy           |
| [Troubleshooting](docs/troubleshooting.md)                | organised by `flydocs doctor` check IDs         |
| [Contributing operations](docs/skill-operations.md)       | registering a skill's script with `flydocs run` |

## Links

- **Website**: [flydocs.ai](https://www.flydocs.ai)
- **Source**: [github.com/plastrlab/flydocs-core](https://github.com/plastrlab/flydocs-core)

## License

Proprietary - All rights reserved.