# Query Context

Context Nest gives you two ways to pull from your vault: `ctx resolve` for a metadata list of matches, and `ctx query` for full, graph-aware context retrieval.

## Selectors

Both commands take a **selector**. The selector grammar:

| Form | Matches |
|------|---------|
| `#tag` (or `tag:#tag`) | Documents carrying a tag |
| `type:X` | Documents of a node type |
| `[[Title]]` | A document by title |
| `scope:X` | Documents in a visibility scope |

Combine selectors with these operators:

| Operator | Meaning |
|----------|---------|
| `+` | AND (intersection) |
| `\|` | OR (union) |
| `-` | NOT (exclude) |

```bash
ctx resolve "#engineering"                 # documents with a tag
ctx resolve "type:document +status:published"  # intersection
ctx resolve "#api |#v2"                    # union
ctx resolve "#api -#deprecated"            # exclude
```

> Note: the operators are `+`, `|`, `-`. The `&` operator used in older docs is no longer valid — `ctx` rejects it with `INVALID_SELECTOR`.

## Resolve (metadata)

```bash
ctx resolve "#engineering"
```

Returns a list of matching documents with their ids, types, and status — no bodies.

## Query (full context)

```bash
ctx query "#engineering"                   # all docs with a tag
ctx query "type:document"                  # all docs of a type
ctx query "pack:engineering-essentials"    # all docs in a pack
ctx query "#api +status:published"         # intersection
ctx query "#api |#v2"                      # union
```

Returns the full document content in hydration order plus trace entries.

### Published-only by default

`ctx query` returns **published documents only** by default. To include drafts (for example while authoring), add `--include-drafts`:

```bash
ctx query "#engineering"                    # published only
ctx query "#engineering" --include-drafts   # published + drafts
```

### Graph traversal (`--hops`)

`ctx query` is graph-aware: from the matched nodes it follows links outward to pull in the surrounding neighborhood. Control the depth with `--hops` (default: 2). Use `--hops 0` for just the matches, `1` for matches + direct links, higher to reach further:

```bash
ctx query "[[API Design Guide]]" --hops 1   # the doc + its direct links
ctx query "#engineering" --hops 0           # just the matches, no traversal
```

Add `--full` to force full-load mode (load all documents rather than graph-walking), and `--json` for machine-readable output.

## Cloud packs *(coming soon)*

Cloud packs will allow querying context from hosted packs without downloading source files:

```bash
ctx query @promptowl/executive-ai-strategy
```

See [Cloud Packs](https://nest.promptowl.ai/d/promptowl-documents/protocol/context-packs/cloud-packs) for the planned design.

## JSON output

All query commands support `--json` for programmatic consumption:

```bash
ctx query "pack:engineering-essentials" --json
```

## Search

Full-text search across all vault documents (separate from selector queries):

```bash
ctx search "rate limiting"
ctx search "rate limiting" --limit 5 --json
```