<!-- rye:signed:2026-03-17T01:08:18Z:a506b6a12dba813bb5419168fa64a111f4b2c190eadf3b869ede031fca69844a:AdHdUghFaq_5NiawQJMTDWxfNwPHonSEIe3MKm4q_knwWlZIbOsD0JzA5AeAgRHH6fe82CfnS1WCEgDMiX5XDg==:6ea18199041a1ea8 -->

```yaml
name: terminology
title: Rye OS Terminology & Naming Conventions
entry_type: reference
category: rye/core
version: "1.0.0"
author: rye-os
created_at: 2026-02-18T00:00:00Z
tags:
  - terminology
  - naming
  - conventions
  - item-types
  - directive
  - tool
  - knowledge
  - spaces
  - project
  - user
  - system
  - item-id
  - namespace
references:
  - "docs/getting-started/quickstart.md"
```

# Rye OS Terminology & Naming Conventions

Canonical vocabulary and naming rules for the Rye OS project.

## Project Names

| Term       | Usage                                                                 |
| ---------- | --------------------------------------------------------------------- |
| **Rye OS** | The full product name (two words, capital R, capital OS)               |
| **RYE**    | Acronym form — used in env vars (`RYE_PYTHON`, `RYE_PARENT_THREAD_ID`) |
| **rye**    | Lowercase — Python package name (`import rye`), CLI, pip install name |
| **ryeos**  | PyPI package — standard bundle (`pip install ryeos`)                  |
| **ryeos-core** | Minimal install — rye/core only (`pip install ryeos-core`)        |
| **ryeos-bare** | Engine only — no .ai/ items (`pip install ryeos-bare`)            |
| **ryeos-web** | Opt-in web bundle — rye/web/* (`pip install ryeos-web`)            |
| **ryeos-code** | Opt-in code bundle — rye/code/* (`pip install ryeos-code`)        |
| **ryeos-mcp** | The MCP server package                                              |
| **Lilux**  | The low-level primitives layer (subprocess, HTTP, integrity, signing) |

## The Three Item Types

| Item Type     | What It Is                                  | File Format                    | Storage Directory     |
| ------------- | ------------------------------------------- | ------------------------------ | --------------------- |
| **directive** | Multi-step workflow definition for agents   | `.md` (Markdown + embedded XML) | `.ai/directives/`     |
| **tool**      | Executable script or config                 | `.py`, `.yaml`, `.sh`, `.js`   | `.ai/tools/`          |
| **knowledge** | Domain information, patterns, learnings     | `.md` (Markdown + YAML frontmatter) | `.ai/knowledge/`  |

## ID Conventions

### Item IDs

The item ID is the **relative path** from `.ai/<type>/` to the file, **without the file extension**.

```
.ai/directives/rye/core/create_directive.md  →  item_id = "rye/core/create_directive"
.ai/tools/rye/bash/bash.py                   →  item_id = "rye/bash/bash"
.ai/knowledge/project_conventions.md         →  item_id = "project_conventions"
```

### Case Rules

| Context                | Convention     | Example                          |
| ---------------------- | -------------- | -------------------------------- |
| Directive file names   | `snake_case`   | `create_directive.md`            |
| Tool file names        | `snake_case`   | `bash.py`, `python/script.yaml` |
| Knowledge file names   | `kebab-case`   | `directive-metadata-reference.md` |
| Knowledge IDs          | `kebab-case`   | `directive-metadata-reference`   |
| Directive names (XML)  | `snake_case`   | `<directive name="create_directive">` |
| Namespace directories  | `kebab-case`   | `rye/file-system/`, `rye/core/` |
| Bundle IDs             | `kebab-case`   | `ryeos-core`, `ryeos`           |
| Env vars               | `UPPER_SNAKE`  | `USER_SPACE`, `RYE_PYTHON`      |
| Capability strings     | `dot.separated`| `rye.execute.tool.rye.bash.bash` |
| Python packages        | `snake_case`   | `rye_core`, `rye_mcp`           |

### Namespace Convention

Items are organized into namespaces using directory nesting. The first path segment identifies the owner.

```
rye/core/     — ships with rye-os (standard library)
rye/bash/     — built-in bash tools
rye/web/      — built-in web tools
rye/file-system/ — built-in file system tools
rye/agent/    — thread orchestration system
<project>/    — project-specific items
```

## MCP Tool Names

The four MCP-exposed tools use the `rye_` prefix:

| MCP Tool      | Purpose                           |
| ------------- | --------------------------------- |
| `rye_execute` | Execute directives, tools, knowledge |
| `rye_search`  | Search across items               |
| `rye_load`    | Load/inspect/copy items           |
| `rye_sign`    | Validate and sign items           |

## Key Concepts

| Term               | Definition                                                        |
| ------------------ | ----------------------------------------------------------------- |
| **space**          | One of three resolution tiers: project, user, system              |
| **chain**          | The tool → runtime → primitive execution path                     |
| **primitive**      | Terminal chain node — maps to a Lilux class (subprocess, HTTP)    |
| **runtime**        | YAML config defining how a tool type is executed                  |
| **bundle**         | Packaged collection of items distributed as a Python package      |
| **integrity**      | SHA-256 content hash + Ed25519 signature verification             |
| **lockfile**       | Pinned chain with integrity hashes for reproducible execution     |
| **capability**     | Permission token controlling what a thread can do                 |
| **thread**         | Isolated LLM execution context with limits and permissions        |
| **anchor**         | Module resolution root for multi-file tool dependencies           |
| **extractor**      | YAML config defining how metadata is indexed per item type        |
| **sink**           | Output destination for thread events (file, websocket, null)      |
