Local Sync & AI Hub
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Local Sync & AI Hub system serves as a governance and synchronization layer within the Everything Claude Code (ECC) ecosystem. It ensures that local project configurations, documentation, and agent specialized knowledge remain synchronized with centralized repositories while adhering to strict portability and security guardrails. Its primary function is to manage the flow of "source-of-truth" data between the local development environment and external AI-hubs.
This module enforces the principle that configurations emitted locally must remain portable (using relative paths like ${HOME}/relativo) and prohibits the unauthorized pushing of governance or self-configuration to external repositories without explicit operator authorization, as defined in AGENTS.md R10 and .ai-hub ADR-0001.
Sources: commands/update-docs.md:7, local/commands/local-sync-ai-hub.md
Synchronization Architecture
The synchronization process is designed to be a multi-stage workflow that identifies, validates, and distributes codebase intelligence. It bridges the gap between the raw source code and the synthesized knowledge stored in documentation and codemaps.
Knowledge Layering
The system operates across several distinct knowledge layers to ensure that synchronization does not lead to data duplication or leakage of sensitive information.
| Layer | Function | Primary Storage |
|---|---|---|
| Active Execution | Current operational state | GitHub/Linear |
| Quick Access | Cross-session context | ~/.claude/projects/*/memory/ |
| Durable Store | Synthesized research/notes | Knowledge base repo |
| Semantic Layer | Relationship mapping | MCP Memory Server |
Sources: skills/knowledge-ops/references/summary.md:20-55
Data Flow Diagram
The following diagram illustrates how the ai-sync-ecc.js script and the update-docs command interact to maintain the project hub.
Core Components & Logic
Source of Truth Identification
The system extracts documentation directly from the codebase to maintain a "Single Source of Truth." This prevents manual editing of generated sections and ensures that documentation accurately reflects the actual state of the code.
- Script Extraction: Reads
package.json,Makefile, orCargo.tomlto generate command reference tables. - Environment Mapping: Parses
.env.exampleto categorize variables as required or optional and document expected formats. - API Documentation: Uses
openapi.yamland route files to build API endpoint references.
Sources: commands/update-docs.md:13-35, agents/doc-updater.md:58-60
Security and Portability Guardrails
A critical aspect of the Local Sync & AI Hub is the enforcement of security rules during the synchronization process.
- Path Portability: All emitted configurations must use relative paths. Absolute paths are strictly forbidden to ensure the hub remains portable across different environments.
- Redaction: Sensitive data (API keys, passwords, tokens) must be redacted from any Git-tracked files or memory updates before synchronization.
- Audit Logs: The system generates staleness checks and analysis reports (e.g.,
.reports/codemap-diff.txt) to track changes and flag outdated documentation for manual review.
Sources: commands/update-docs.md:7, skills/knowledge-ops/references/summary.md:121, commands/update-docs.md:65-75
Automated Codemap Generation
The doc-updater agent and scripts/codemaps/generate.ts work together to create architectural maps that summarize the codebase for the AI hub.
Governance Rules
The following table outlines the mandatory rules for maintaining the Local Sync and AI Hub interface:
| Rule ID | Name | Requirement |
|---|---|---|
| R1 | Single Source of Truth | Always generate from code, never manually edit generated sections. |
| R2 | Auto-Generated Markers | Use <!-- AUTO-GENERATED --> markers around synced sections. |
| R3 | Portability | Use ${HOME} relative paths; never use absolute paths. |
| R4 | Authorization | Unauthorized pushing of self-config requires explicit operator consent (ADR-0001). |
| R5 | Redaction | Redact API keys and PII before committing to Git. |
Sources: commands/update-docs.md:7, 80-85, AGENTS.md:R10, skills/knowledge-ops/references/summary.md:121
Conclusion
The Local Sync & AI Hub is a vital infrastructure component of ECC that automates the maintenance of codebase intelligence while upholding strict security and portability standards. By centralizing the "Source of Truth" in the code itself and using specialized agents to sync this data into structured documentation and codemaps, the system ensures that AI assistants always have access to accurate, up-to-date, and safe project context.