# gnos

gnos is a local-first tool for managing document chunks as manifests. Add files, attest reproducibility, and materialize documents back to disk.

## Quick start

```bash
gnos init

gnos add README.md

gnos materialize doc <doc_id> --output README.out.md
```

## What you can do

- Add files and store their chunks locally.
- Generate doc-manifests that describe how to reconstruct the original bytes.
- Attest that a manifest can reproduce the original document.
- Materialize documents back to disk when you need them.
- Bring your own chunkers for custom strategies.

## Why use gnos?

- **Verifiable manifests.** A stable schema that actually reconstructs the original bytes.
- **Local chunk store.** Chunks are content-addressed and live on your machine.
- **Rebuild anytime.** Materialize documents back to disk from manifests + chunks.
- **Derive safely.** Create alternate chunk views without changing identity.

Compared to typical chunking tools, gnos gives you a concrete manifest format and a local store you can trust.

## Common workflows

### Add a file

```bash
gnos add notes.md
```

### Add a directory as a collection

```bash
gnos add --collection docs/
```

### Verify a manifest directly

```bash
gnos attest manifest <manifest_hash>
```

### Shallow integrity check (hash-only)

```bash
gnos attest manifest <manifest_hash> --shallow
```

### Derive a non-identity manifest

```bash
gnos derive <doc_manifest_hash> --chunking <method>
```

### Materialize a collection

```bash
gnos materialize collection <collection_id> --dir ./out
```

## Commands (v1)

- `gnos init`
- `gnos add <path>`
- `gnos add --collection <path>`
- `gnos attest manifest <manifest_hash> [--doc-id H] [--shallow]`
- `gnos attest file <path> --doc-id H`
- `gnos attest doc <doc_id>`
- `gnos derive <manifest_hash> --chunking <method>`
- `gnos materialize doc <doc_id> --output <path>`
- `gnos materialize collection <collection_id> --dir <path>`
- `gnos status [--doc <doc_id>]`
- `gnos chunker list [--verbose]`
- `gnos inspect <hash>`
- `gnos list --objects|--documents|--document-manifests|--collection-manifests|--derived-manifests`
- `gnos --version`

## How it works (short)

- Documents are raw bytes. The document hash is the identity.
- Chunks are stored by hash. Manifests describe how to reconstruct bytes.
- Attestation verifies integrity and, when applicable, reconstruction.

## Learn more

- `docs/index.md` (overview of all docs)
- `docs/spec.md` (v1 spec)
- `docs/cli.md` (CLI behavior)
- `docs/manifest.md` (manifest schemas)
- `docs/chunking.md` (chunker rules)
- `docs/plugins.md` (custom chunkers)
