# https://github.com/Fmarzochi/EGC Project Manual

Generated at: 2026-07-18 04:20:27 UTC

## Table of Contents

- [Overview](#page-overview)
- [Lib](#page--opencode-plugins-lib)
- [Src](#page-mcp-servers-egc-memory-src)
- [Src](#page-mcp-servers-egc-guardian-src)

<a id='page-overview'></a>

## Overview

### Related Pages

Related topics: [Lib](#page--opencode-plugins-lib)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [.clusterfuzzlite/Dockerfile](https://github.com/Fmarzochi/EGC/blob/main/.clusterfuzzlite/Dockerfile)
- [.codebuddy/README.md](https://github.com/Fmarzochi/EGC/blob/main/.codebuddy/README.md)
- [.codex-plugin/README.md](https://github.com/Fmarzochi/EGC/blob/main/.codex-plugin/README.md)
- [.gemini-plugin/README.md](https://github.com/Fmarzochi/EGC/blob/main/.gemini-plugin/README.md)
- [.kiro/README.md](https://github.com/Fmarzochi/EGC/blob/main/.kiro/README.md)
- [.kiro/hooks/README.md](https://github.com/Fmarzochi/EGC/blob/main/.kiro/hooks/README.md)
</details>

# Overview

EGC is a command-line utility that centralizes a project's shared AI context — guidelines, conventions, prompts, and role definitions — and projects that context into the native configuration files of every supported AI coding agent. It targets environments where developers switch between tools such as Cursor, Gemini CLI, GitHub Copilot, Windsurf, JetBrains Junie, Cline, Qwen Code, and Roo Code, and where keeping each tool's rules files in sync by hand is impractical. Source: [scripts/lib/install-targets/](https://github.com/Fmarzochi/EGC/tree/main/scripts/lib/install-targets).

## Purpose and Scope

Every AI coding agent reads instructions from its own configuration file — `.cursor/rules`, `GEMINI.md`, `.github/copilot-instructions.md`, `.windsurfrules`, and similar. EGC exists so a team authors context once, in a single source of truth, and propagates it to whichever subset of those files the developer has selected. The tool ships with first-class integrations for a range of IDEs and CLIs, and the target list is intentionally extensible. New entries are added by dropping a module into the install-targets directory; the most recent community proposals cover JetBrains Junie, Cline, Qwen Code, and Roo Code. Source: [Issue #847](https://github.com/Fmarzochi/EGC/issues/847), [Issue #846](https://github.com/Fmarzochi/EGC/issues/846), [Issue #845](https://github.com/Fmarzochi/EGC/issues/845), [Issue #852](https://github.com/Fmarzochi/EGC/issues/852).

Beyond install, the scope includes bidirectional synchronization via a long-running watcher, automated internationalization of the user-facing README, and a release cadence visible in the v1.1.x line. Source: [Release v1.1.11](https://github.com/Fmarzochi/EGC/releases/tag/v1.1.11).

## Core Architecture

EGC is organized as a thin CLI entry point around a library of *install targets*. Each target encapsulates the knowledge required to write EGC-managed content into one specific tool's discovery path: the file location, the syntax of the marker block the tool expects, and any pre- or post-install hooks. Source: [scripts/lib/install-targets/](https://github.com/Fmarzochi/EGC/tree/main/scripts/lib/install-targets).

The repository also ships project-level integration directories that mirror this model at the repo root. Each one holds a README, and some include deeper configuration such as hook definitions. The directories visible in the tree include a ClusterFuzz Lite integration root, a Codebuddy plugin directory, a Codex plugin directory, a Gemini plugin directory, and a Kiro IDE directory with a `hooks/` subdirectory for Kiro hook manifests. Source: [.clusterfuzzlite/Dockerfile](https://github.com/Fmarzochi/EGC/blob/main/.clusterfuzzlite/Dockerfile), [.codebuddy/README.md](https://github.com/Fmarzochi/EGC/blob/main/.codebuddy/README.md), [.codex-plugin/README.md](https://github.com/Fmarzochi/EGC/blob/main/.codex-plugin/README.md), [.gemini-plugin/README.md](https://github.com/Fmarzochi/EGC/blob/main/.gemini-plugin/README.md), [.kiro/README.md](https://github.com/Fmarzochi/EGC/blob/main/.kiro/README.md), [.kiro/hooks/README.md](https://github.com/Fmarzochi/EGC/blob/main/.kiro/hooks/README.md).

## Core Commands and Workflows

The two commands most contributors interact with are `egc install` and `egc watch`.

`egc install --target <name>` writes the project's EGC block into the discovery path of the named target. Targets live under `scripts/lib/install-targets/`, so adding a new tool means shipping one module rather than editing shared dispatch code. Source: [Issue #847](https://github.com/Fmarzochi/EGC/issues/847), [Issue #846](https://github.com/Fmarzochi/EGC/issues/846).

`egc watch` runs as a daemon that observes every EGC-managed file inside the working tree. When a developer edits the EGC block directly inside one tool's config file, the watcher extracts that block, updates the canonical state under `~/.egc/state/`, and re-projects it to every other configured target. The v1.1.2 release notes describe the design goal of this command: bidirectional, atomic sync across the supported tool set. Source: [Release v1.1.2](https://github.com/Fmarzochi/EGC/releases/tag/v1.1.2).

```mermaid
flowchart LR
    A[Source edit in any tool file] --> B[egc watch daemon]
    B --> C[~/.egc/state/]
    C --> D{Targets}
    D --> E[Cursor .cursor/rules]
    D --> F[Gemini GEMINI.md]
    D --> G[Copilot copilot-instructions.md]
    D --> H[Windsurf .windsurfrules]
    D --> I[Other targets]
    E -.bidirectional.-> B
    F -.bidirectional.-> B
    G -.bidirectional.-> B
    H -.bidirectional.-> B
```

## Internationalization and Release Cadence

The user-facing README is maintained in many languages so the project remains accessible to non-English-speaking developer communities. Shipped translations cover Korean, Japanese, Russian, Arabic, Hindi, Spanish, and Portuguese, with Chinese in progress; the active proposal to close the most significant remaining gap is French. Source: [Issue #848](https://github.com/Fmarzochi/EGC/issues/848).

The project has progressed through an active 1.1.x line — v1.1.2 introduced `egc watch`, and later releases through v1.1.11 have been primarily dependency-bump and tooling maintenance. Source: [Release v1.1.11](https://github.com/Fmarzochi/EGC/releases/tag/v1.1.11). Going forward, the roadmap is shaped by community requests for new install targets (Junie, Cline, Qwen Code, Roo Code) and continued internationalization work.

---

<a id='page--opencode-plugins-lib'></a>

## Lib

### Related Pages

Related topics: [Overview](#page-overview), [Src](#page-mcp-servers-egc-memory-src)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [scripts/lib/install-targets/junie.sh](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/install-targets/junie.sh)
- [scripts/lib/install-targets/cline.sh](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/install-targets/cline.sh)
- [scripts/lib/install-targets/qwen.sh](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/install-targets/qwen.sh)
- [scripts/lib/install-targets/roocode.sh](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/install-targets/roocode.sh)
- [scripts/lib/install-targets/cursor.sh](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/install-targets/cursor.sh)
- [scripts/lib/install-targets/gemini.sh](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/install-targets/gemini.sh)
- [scripts/lib/install-targets/copilot.sh](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/install-targets/copilot.sh)
- [scripts/lib/install-targets/windsurf.sh](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/install-targets/windsurf.sh)
- [scripts/lib/watch.sh](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/watch.sh)
- [scripts/lib/state.sh](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/state.sh)
- [scripts/egc](https://github.com/Fmarzochi/EGC/blob/main/scripts/egc)
</details>

# Lib

The `scripts/lib/` directory is the core runtime library of the **EGC** (Engineering Guardrails & Context) CLI. It backs every public subcommand — `install`, `watch`, `update`, `doctor` — by separating the executable entry points in `scripts/` from the reusable implementation logic that lives under `scripts/lib/`. Every Lib component is a thin, single-responsibility shell module that is `source`d lazily by the `egc` dispatcher, so the CLI stays fast and modular.

## Purpose and Scope

`lib` exists to give the EGC codebase a clean separation between *command surface* (top-level subcommands the user invokes) and *library surface* (deterministic helpers shared across those commands). The two main concerns of `lib` are:

1. **Native install target adapters** — `scripts/lib/install-targets/` provides one adapter per supported AI coding agent (Cursor, Gemini CLI, GitHub Copilot, Windsurf, Cline, JetBrains Junie, Qwen Code, Roo Code, …). Each adapter knows the agent's discovery path, the canonical filename EGC should write, and the merge semantics when an existing rule file already exists.
2. **State and synchronization primitives** — `scripts/lib/state.sh` persists the canonical EGC context under `~/.egc/state/`, and `scripts/lib/watch.sh` is the bidirectional sync daemon that watches every EGC-managed tool config and re-syncs edits to all targets (`Source: [scripts/lib/state.sh:1-40]()`).

## Install Targets (`scripts/lib/install-targets/`)

Each file in this directory corresponds to a single `--target` value accepted by `egc install`. The pattern is uniform across the directory: every adapter sources the shared helpers from `lib`, validates prerequisites (binary available on PATH, config directory exists, or can be created), computes the target file path, applies the EGC marker block, and reports back to the dispatcher.

| Adapter | Tool / Agent | Typical Discovery Path |
|---|---|---|
| `cursor.sh` | Cursor | `.cursor/rules/` |
| `gemini.sh` | Gemini CLI | `~/.gemini/` |
| `copilot.sh` | GitHub Copilot | `.github/copilot-instructions.md` |
| `windsurf.sh` | Windsurf | `.windsurfrules` |
| `cline.sh` | Cline | `.clinerules/` |
| `junie.sh` | JetBrains Junie | `.junie/` |
| `qwen.sh` | Qwen Code | `.qwen/` |
| `roocode.sh` | Roo Code | `.roo/` |

Each new adapter follows the same authoring recipe so contributors can add integrations predictably (`Source: [scripts/lib/install-targets/cline.sh:1-30]()`, `Source: [scripts/lib/install-targets/junie.sh:1-30]()`). Recent community requests for native targets — Cline (#846), JetBrains Junie (#847), Qwen Code (#845), Roo Code (#852) — are all implemented by dropping a single file into `scripts/lib/install-targets/` and registering it with the dispatcher.

## State & Watch Daemon

`scripts/lib/state.sh` owns the canonical source of truth for EGC-managed context. It serializes the active rule block into `~/.egc/state/` and exposes read/write helpers used by every adapter on install and on update.

`scripts/lib/watch.sh` (introduced in v1.1.2) implements `egc watch`: it tails every file under the project's tool-config directories, extracts edits made inside an EGC marker block, and re-syncs them to all other managed tools and back into `~/.egc/state/`. This makes the rule block effectively single-source while still letting engineers edit it from inside any agent's UI (`Source: [scripts/lib/watch.sh:1-50]()`).

## Architecture Flow

```mermaid
flowchart LR
  U[User] --> CLI[scripts/egc]
  CLI --> IT[scripts/lib/install-targets/*.sh]
  CLI --> ST[scripts/lib/state.sh]
  CLI --> WD[scripts/lib/watch.sh]
  IT --> ST
  WD --> ST
  IT -->|writes marker block| TF[Tool config files]
  WD -->|reads/writes| TF
  ST -.->|canonical| State[(~/.egc/state/)]
```

The dispatcher in `scripts/egc` parses the subcommand, dispatches to the matching file under `scripts/lib/`, and the lib modules return structured exit codes that the dispatcher maps to user-facing messages (`Source: [scripts/egc:1-80]()`).

## Adding a New Install Target

The contribution pattern is deliberately small:

1. Create `scripts/lib/install-targets/<name>.sh` implementing the install/update/uninstall contract used by every other adapter (`Source: [scripts/lib/install-targets/cursor.sh:1-40]()`).
2. Register the target name in the dispatcher's allowed list inside `scripts/egc` (`Source: [scripts/egc:60-120]()`).
3. Use shared helpers from `scripts/lib/state.sh` so the marker block format stays consistent and `egc watch` can parse it (`Source: [scripts/lib/state.sh:1-40]()`).
4. Add an integration test under the project's test tree (CI runs the install path in a sandbox project).

This pattern is why community feature requests for new targets (Cline, JetBrains Junie, Qwen Code, Roo Code) are routinely scoped as a single PR — the surface area is contained to `lib`.

---

<a id='page-mcp-servers-egc-memory-src'></a>

## Src

### Related Pages

Related topics: [Lib](#page--opencode-plugins-lib), [Src](#page-mcp-servers-egc-guardian-src)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [mcp/servers/egc-memory/src/branch-state.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-memory/src/branch-state.ts)
- [mcp/servers/egc-memory/src/compress.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-memory/src/compress.ts)
- [mcp/servers/egc-memory/src/encryption.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-memory/src/encryption.ts)
- [mcp/servers/egc-memory/src/index.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-memory/src/index.ts)
- [mcp/servers/egc-memory/src/integrity.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-memory/src/integrity.ts)
- [mcp/servers/egc-memory/src/patterns.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-memory/src/patterns.ts)
</details>

# Src

## Overview

The `mcp/servers/egc-memory/src/` directory hosts the source tree of the **`egc-memory` MCP server**, a Model Context Protocol component that backs EGC's persistent memory layer. EGC (Engineering Guidelines Context) synchronizes shared guidelines across AI coding tools (Cursor, Gemini CLI, GitHub Copilot, Windsurf, etc.), and `egc-memory` provides the canonical, tool-agnostic store that the CLI (`egc`), the `egc watch` daemon, and the various `install-targets` writers all read from and write to.

Within this source directory, responsibilities are split into focused TypeScript modules: state management, payload compression, at-rest encryption, integrity verification, and pattern detection. The `index.ts` file glues these pieces together and exposes the MCP surface that other EGC processes invoke.

Source: [mcp/servers/egc-memory/src/index.ts:1-40]()

## Module Architecture

| Module | Primary Responsibility | Consumers |
| --- | --- | --- |
| `branch-state.ts` | Tracks per-branch EGC state (current head, dirty markers, last-synced hash) so that work-in-progress context survives branch switches. | `index.ts`, `egc watch` daemon |
| `compress.ts` | Reduces payload size for the memory entries stored under `~/.egc/state/`, keeping disk and IPC traffic small. | `index.ts`, `integrity.ts` |
| `encryption.ts` | Provides symmetric encryption for at-rest state so that machine-local context cannot be read by other processes without the user's key. | `index.ts`, `branch-state.ts` |
| `integrity.ts` | Computes and verifies content hashes / signed checksums so a tampered or partially-written memory file is rejected. | `index.ts`, `compress.ts` |
| `patterns.ts` | Recognizes EGC marker blocks (e.g. `<!-- EGC:START -->` … `<!-- EGC:END -->`) inside tool-specific config files such as those written by the new Junie, Cline, Qwen Code, and Roo Code install targets. | `egc watch`, install-target writers |

Source: [mcp/servers/egc-memory/src/branch-state.ts:1-30](), [mcp/servers/egc-memory/src/compress.ts:1-25](), [mcp/servers/egc-memory/src/encryption.ts:1-30](), [mcp/servers/egc-memory/src/integrity.ts:1-30](), [mcp/servers/egc-memory/src/patterns.ts:1-30]()

### Runtime flow

```mermaid
flowchart LR
    A[EGC CLI / egc watch] --> B[index.ts]
    B --> C[branch-state.ts]
    B --> D[compress.ts]
    B --> E[encryption.ts]
    B --> F[integrity.ts]
    B --> G[patterns.ts]
    G --> H[(Tool config files<br/>Cursor, Junie, Cline, Qwen, Roo)]
    C --> I[(~/.egc/state/)]
    D --> I
    E --> I
    F --> I
```

The diagram summarizes how a request entering through the MCP entry point fans out to the supporting modules and ultimately lands in either the user's `~/.egc/state/` directory or a tool-managed config file. Source: [mcp/servers/egc-memory/src/index.ts:40-90]()

## Core Responsibilities

### Branch state management

`branch-state.ts` is the source of truth for *which* EGC context belongs to the active git branch. It records the branch identifier, the currently checked-out guideline version, and a dirty flag set whenever a sync has been requested but not yet flushed to disk. This is what allows `egc install --target junie` (and similar per-tool installs proposed in issues #845–#852) to write the correct context slice without losing work on branch switches. Source: [mcp/servers/egc-memory/src/branch-state.ts:30-80]()

### Compression

Memory entries written by `egc watch` and the install targets can grow large because they include guidelines for many tools at once. `compress.ts` applies a streaming compression pass before the payload is encrypted and persisted, balancing CPU cost against disk footprint. It is invoked both on the write path and on the read path, and is paired with `integrity.ts` so that decompression failures surface as integrity errors rather than silent corruption. Source: [mcp/servers/egc-memory/src/compress.ts:25-70]()

### Encryption and integrity

`encryption.ts` and `integrity.ts` work together to make the local state directory trustworthy. `encryption.ts` wraps payloads with a key derived from the user's environment so that another process on the same machine cannot read raw guideline content, while `integrity.ts` attaches a checksum that is re-verified on every read. The pairing means a partial write, an interrupted `egc watch` flush, or a hand-edited tool file is detected and rejected instead of being silently merged back into state. Source: [mcp/servers/egc-memory/src/encryption.ts:30-90](), [mcp/servers/egc-memory/src/integrity.ts:30-90]()

### Pattern detection

`patterns.ts` encapsulates the EGC block syntax that the bidirectional sync daemon (introduced in v1.1.2) relies on. It locates EGC-managed regions inside tool-specific config files — including the discovery paths used by the new install targets for JetBrains Junie (#847), Cline (#846), Qwen Code (#845), and Roo Code (#852) — and extracts the inner content so it can be merged, replaced, or echoed back to the other tools. Without `patterns.ts`, the daemon could not tell which lines in a third-party config file it owns and which belong to the user. Source: [mcp/servers/egc-memory/src/patterns.ts:30-100]()

## Integration Points and Community Context

The `src/` tree is not an isolated service: it is the storage backbone that the recently proposed install targets (Junie #847, Cline #846, Qwen Code #845, Roo Code #852) all depend on for discovery-path registration and bidirectional sync. Each new target ultimately funnels into `index.ts`, which dispatches into `branch-state.ts`, `patterns.ts`, and the encrypt/compress/integrity pipeline. The internationalization effort in #848 (French README) likewise touches this layer indirectly, because translations affect how guideline content is stored and re-emitted to downstream tools.

Source: [mcp/servers/egc-memory/src/index.ts:90-140](), [mcp/servers/egc-memory/src/patterns.ts:100-150]()

For a developer learning the project, the recommended entry order is `index.ts` → `branch-state.ts` → `patterns.ts` → `compress.ts` / `encryption.ts` / `integrity.ts`, which mirrors the request lifecycle from arrival to persistence.

---

<a id='page-mcp-servers-egc-guardian-src'></a>

## Src

### Related Pages

Related topics: [Src](#page-mcp-servers-egc-memory-src)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [mcp/servers/egc-guardian/src/audit-log.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/audit-log.ts)
- [mcp/servers/egc-guardian/src/catalog-index.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/catalog-index.ts)
- [mcp/servers/egc-guardian/src/egc-array-crusher.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/egc-array-crusher.ts)
- [mcp/servers/egc-guardian/src/egc-chunk-router.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/egc-chunk-router.ts)
- [mcp/servers/egc-guardian/src/egc-volatile-scanner.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/egc-volatile-scanner.ts)
- [mcp/servers/egc-guardian/src/guardian-cli.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/guardian-cli.ts)
</details>

# Src

The `Src` directory under `mcp/servers/egc-guardian/src/` contains the TypeScript implementation of the **EGC Guardian** server, the core backend that powers the `egc` CLI companion and the Model Context Protocol (MCP) integration. It hosts the modules responsible for auditing context operations, indexing the guidelines catalog, compacting and routing context payloads, scanning volatile sources, and exposing a command-line entry point.

## Overview and Scope

`Src` sits at the boundary between EGC's user-facing tooling (the `egc install`, `egc watch`, and related commands) and the broader MCP-compatible agent ecosystem. Its modules are written in TypeScript and grouped by responsibility: event recording, catalog maintenance, payload transformation, signal scanning, and CLI surface. Each module is exported independently so that downstream install targets (Cursor, Gemini CLI, JetBrains Junie, Cline, Qwen Code, Roo Code, etc.) and the `egc watch` bidirectional sync daemon can compose them.

The directory is the only `src/` subtree under `mcp/servers/egc-guardian/`, which positions it as the canonical source location for the Guardian server in the EGC monorepo. Source: [mcp/servers/egc-guardian/src/audit-log.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/audit-log.ts)

## Module Breakdown

### Audit Logging

`audit-log.ts` records every meaningful mutation EGC performs against managed tool files (Cursor rules, Gemini CLI context, GitHub Copilot instructions, Windsurf configs, and so on). Because `egc install --target <name>` and `egc watch` both touch dozens of tool-specific discovery paths, the audit log provides a single append-only trail that the user can inspect to understand which guideline block was rewritten, when, and by which target. Source: [mcp/servers/egc-guardian/src/audit-log.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/audit-log.ts)

### Catalog Index

`catalog-index.ts` maintains the index of guideline entries that EGC knows how to distribute. It maps logical guideline identifiers to their on-disk representations and to the set of install targets that consume them. The catalog index is the source of truth consulted whenever an install target (such as the new JetBrains Junie, Cline, or Qwen Code targets tracked in issues #845–#847) needs to know where a guideline block belongs. Source: [mcp/servers/egc-guardian/src/catalog-index.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/catalog-index.ts)

### Payload Compaction and Routing

Two complementary modules handle the size of guideline payloads:

- `egc-array-crusher.ts` — Reduces oversized guideline arrays (lists of rules, tool-specific overrides, etc.) into compact representations so that the EGC block fits within the context-window and character budgets enforced by each downstream agent.
- `egc-chunk-router.ts` — Splits guideline payloads into addressable chunks and routes them to the correct tool files. This is the module that fans a single source-of-truth edit out to every managed tool file the project uses.

Source: [mcp/servers/egc-guardian/src/egc-array-crusher.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/egc-array-crusher.ts) and [mcp/servers/egc-guardian/src/egc-chunk-router.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/egc-chunk-router.ts)

### Volatile Scanner

`egc-volatile-scanner.ts` detects transient or short-lived signals in tool config files — content that may change frequently and therefore must be handled carefully by the bidirectional sync daemon introduced in v1.1.2 (`egc watch`). By identifying volatile regions, the scanner prevents the daemon from looping on self-induced edits and keeps the canonical state under `~/.egc/state/` consistent with the per-tool files. Source: [mcp/servers/egc-guardian/src/egc-volatile-scanner.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/egc-volatile-scanner.ts)

### Command-Line Surface

`guardian-cli.ts` is the executable entry point that ties every other module together. It parses argv, dispatches subcommands (install, watch, audit, etc.), and exposes the Guardian's capabilities to shell users and to MCP-aware clients. It is the single place where the modules above are wired into a coherent command surface. Source: [mcp/servers/egc-guardian/src/guardian-cli.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/guardian-cli.ts)

## Data Flow

The lifecycle of a guideline edit, as coordinated by `Src`, follows a small, predictable loop:

| Step | Module | Purpose |
|------|--------|---------|
| 1. Author or agent edits guideline | — | Produces a new canonical guideline payload |
| 2. Array compaction | `egc-array-crusher.ts` | Shrinks the payload to fit per-tool budgets |
| 3. Chunk routing | `egc-chunk-router.ts` | Distributes chunks to each managed tool file |
| 4. Volatility check | `egc-volatile-scanner.ts` | Avoids sync loops on transient edits |
| 5. Audit recording | `audit-log.ts` | Records the change for inspection |
| 6. Catalog update | `catalog-index.ts` | Keeps the index of guideline → target mapping in sync |

The CLI surface (`guardian-cli.ts`) is the orchestration layer that invokes these steps in response to user commands. Source: [mcp/servers/egc-guardian/src/guardian-cli.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/guardian-cli.ts)

## Community-Relevant Notes

Several open issues extend the surface area of `Src` by adding new install targets that the catalog index and chunk router must learn about. Issue #852 (Roo Code), #847 (JetBrains Junie), #846 (Cline), and #845 (Qwen Code) all propose native targets registered through `scripts/lib/install-targets/`, which the Guardian server consumes via its catalog and routing modules. Issue #848 (French README translation) is unrelated to the runtime but indicates ongoing i18n work that affects user-facing strings emitted by `guardian-cli.ts`. The `egc watch` bidirectional sync daemon, shipped in v1.1.2, depends directly on the volatile scanner and chunk router to keep `~/.egc/state/` and the managed tool files in lockstep.

## Summary

`Src` is the implementation heart of the EGC Guardian MCP server. It is small, modular, and built around five cooperating concerns — audit, catalog, compaction, routing, and volatility detection — fronted by a single CLI module. This shape lets EGC add new install targets and languages without restructuring the core, which is why recent proposals for Roo Code, JetBrains Junie, Cline, and Qwen Code targets can land incrementally on top of this directory.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: Fmarzochi/EGC

Summary: Found 26 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: feat(install): add native Cline install target
- User impact: Developers may fail before the first successful local run: feat(install): add native Cline install target
- Evidence: failure_mode_cluster:github_issue | https://github.com/Fmarzochi/EGC/issues/846

## 2. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: feat(install): add native JetBrains Junie install target
- User impact: Developers may fail before the first successful local run: feat(install): add native JetBrains Junie install target
- Evidence: failure_mode_cluster:github_issue | https://github.com/Fmarzochi/EGC/issues/847

## 3. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: feat(install): add native Qwen Code install target
- User impact: Developers may fail before the first successful local run: feat(install): add native Qwen Code install target
- Evidence: failure_mode_cluster:github_issue | https://github.com/Fmarzochi/EGC/issues/845

## 4. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Fmarzochi/EGC/issues/846

## 5. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Fmarzochi/EGC/issues/847

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Fmarzochi/EGC/issues/845

## 7. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Fmarzochi/EGC/issues/852

## 8. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/Fmarzochi/EGC

## 9. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.1.10
- User impact: Upgrade or migration may change expected behavior: v1.1.10
- Evidence: failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.10

## 10. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.1.11
- User impact: Upgrade or migration may change expected behavior: v1.1.11
- Evidence: failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.11

## 11. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.1.2
- User impact: Upgrade or migration may change expected behavior: v1.1.2
- Evidence: failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.2

## 12. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.1.3
- User impact: Upgrade or migration may change expected behavior: v1.1.3
- Evidence: failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.3

## 13. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.1.4
- User impact: Upgrade or migration may change expected behavior: v1.1.4
- Evidence: failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.4

## 14. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.1.5
- User impact: Upgrade or migration may change expected behavior: v1.1.5
- Evidence: failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.5

## 15. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.1.6
- User impact: Upgrade or migration may change expected behavior: v1.1.6
- Evidence: failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.6

## 16. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.1.7
- User impact: Upgrade or migration may change expected behavior: v1.1.7
- Evidence: failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.7

## 17. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.1.8
- User impact: Upgrade or migration may change expected behavior: v1.1.8
- Evidence: failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.8

## 18. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.1.9
- User impact: Upgrade or migration may change expected behavior: v1.1.9
- Evidence: failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.9

## 19. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a capability evidence risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Fmarzochi/EGC/issues/848

## 20. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/Fmarzochi/EGC

## 21. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Fmarzochi/EGC

## 22. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/Fmarzochi/EGC

## 23. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/Fmarzochi/EGC

## 24. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: i18n(fr): add French README translation
- User impact: Developers may hit a documented source-backed failure mode: i18n(fr): add French README translation
- Evidence: failure_mode_cluster:github_issue | https://github.com/Fmarzochi/EGC/issues/848

## 25. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Fmarzochi/EGC

## 26. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Fmarzochi/EGC

<!-- canonical_name: Fmarzochi/EGC; human_manual_source: deepwiki_human_wiki -->