### [facts](https://github.com/av/facts)

> Handle: `facts`

![facts splash image](./harbor-facts.png)

facts is a CLI for fact-driven development. It reads `.facts` files, lists project truths, validates command-backed facts, and lets coding agents move work from `@draft` to `@spec` to `@implemented`.

## Starting

```bash
harbor build facts
```

facts is a CLI tool that runs on demand, not a persistent web service:

```bash
# Read the current project's fact sheet
harbor facts list

# Verify command-backed facts
harbor facts check

# Add a new fact
harbor facts add "the API returns JSON" --section api --tags spec
```

Harbor runs facts with the caller's current directory mounted as the container working directory, so `harbor facts list` behaves like running `facts list` locally inside that project.

## Configuration

### Environment Variables

Following options can be set via [`harbor config`](./3.-Harbor-CLI-Reference.md#harbor-config):

```bash
HARBOR_FACTS_IMAGE              # Built Harbor image name for the facts CLI
HARBOR_FACTS_VERSION            # Built Harbor image tag
HARBOR_FACTS_BASE_IMAGE         # Base image used to build the CLI container
HARBOR_FACTS_BASE_VERSION       # Base image tag
HARBOR_FACTS_PACKAGE_VERSION    # npm package version for @avcodes/facts
HARBOR_FACTS_WORKSPACE          # Persistent cache directory
```

### Volumes

- `${HARBOR_FACTS_WORKSPACE}` -> `/root/.cache/facts` - persistent cache area for the facts container.
- The directory where `harbor facts ...` is invoked is mounted at the same absolute path inside the container and used as the working directory.

## Troubleshooting

```bash
harbor build facts
harbor facts --version
```

If facts reports that no fact sheet exists, run the command from a project containing `.facts` or initialize one with:

```bash
harbor facts init
```

## Links

- [GitHub Repository](https://github.com/av/facts)
- [npm Package](https://www.npmjs.com/package/@avcodes/facts)
