auto-context-cli 1.0.2__tar.gz → 1.0.4__tar.gz

{auto_context_cli-1.0.2 → auto_context_cli-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: auto-context-cli
-Version: 1.0.2
+Version: 1.0.4
 Summary: Autonomous context & instruction manager for AI coding assistants
 Author: Arghya Biswas
 License: MIT
@@ -20,7 +20,7 @@ Description-Content-Type: text/markdown
 
 [![PyPI - Version](https://img.shields.io/pypi/v/auto-context-cli.svg?color=blue)](https://pypi.org/project/auto-context-cli/)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/auto-context-cli.svg)](https://pypi.org/project/auto-context-cli/)
-[![GitHub Release](https://img.shields.io/github/v/release/Cyber-arghya/auto-context?color=green)](https://github.com/Cyber-arghya/auto-context/releases/tag/v1.0.2)
+[![GitHub Release](https://img.shields.io/github/v/release/Cyber-arghya/auto-context?color=green)](https://github.com/Cyber-arghya/auto-context/releases/tag/v1.0.4)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux%20WSL2-success.svg)](#-quick-one-line-install)
 [![AI Supported](https://img.shields.io/badge/AI%20Supported-Antigravity%20%7C%20Cursor%20%7C%20Claude%20Code%20%7C%20Copilot%20%7C%20Windsurf-orange.svg)](#-supported-ai-assistants)
@@ -75,45 +75,33 @@ cd /path/to/any-project
 init-context
 ```
 
-### Options & Flags:
-```text
-init-context [OPTIONS] [DIRECTORY]
-
-OPTIONS (CONTEXT & RULES):
-  -r, --new-rule <NAME>     Scaffold a new rule file (.agents/rules/<name>.md)
-  -s, --new-skill <NAME>    Scaffold a new skill folder (.agents/skills/<name>/SKILL.md)
-  -g, --global              Target global plugin scope (~/.gemini/config/plugins/auto-context/)
-  -f, --force               Overwrite existing context.md and standing rule files
-  -d, --dry-run             Preview generated structure without writing to disk
-  -v, --version             Display current version
-  -h, --help                Show help documentation
-
-OPTIONS (CENTRAL MEMORY & GRANULAR SHARING):
-  memory init [REPO]        Initialize private central memory repo (~/.auto-context/memory)
-  memory push               Audit secrets & push memory brain to private GitHub repo
-  memory pull [URL]         Pull & sync central memory brain from remote repo
-  memory status             Show status of central memory brain
-  share <NAME>              Audit & publish skill or rule to GitHub Gist
-  import <URL>              Audit & import skill or rule from GitHub Gist or URL
-  update                    Safely update CLI, global plugin & public rules (Non-breaking)
-  update --check            Check for updates without modifying files
-  update -w, --workspace    Update managed system rules in active workspace
-  update -g, --global       Sync global plugin (~/.gemini/config/plugins/auto-context/)
-  update -c, --cli          Upgrade auto-context-cli package via uv/pipx/pip
-  --as <NAME>               Custom name when importing a skill or rule
-  --public                  Publish shared Gist as public (default)
-  --secret, --private       Publish shared Gist as unlisted/secret
-
-OPTIONS (MCP TOOLING):
-  --add-mcp <NAME>          Add or update an MCP server configuration
-  --remove-mcp <NAME>       Remove an MCP server from configuration
-  --list-mcp                List all active MCP server tools
-  --preset <PRESET>         Preset template (sqlite, postgres, github, filesystem, brave, fetch)
-  --command <CMD>           Executable command for stdio server (e.g. npx, uvx, python3)
-  --args <ARGS>             Arguments to pass to command
-  --url <URL>               Streamable HTTP endpoint URL for remote MCP server
-  --env <KEY=VAL,...>       Environment variables (e.g. 'GITHUB_TOKEN=xyz')
-```
+### Command Reference & Syntax:
+
+Auto-Context supports both modern subcommands (`init-context <command>`) and standard legacy flags:
+
+| Command | Shorthand / Flag | Description |
+| :--- | :--- | :--- |
+| `init-context init [DIR]` | `init-context [DIR]` | Scaffolds 5-tier context in active or specified directory. |
+| `init-context scan [DIR]` | `init-context --scan` | Stack-adaptive codebase scanner: generates satellites (.agents/context/). |
+| `init-context rule <name>` | `init-context -r <name>` | Scaffolds a new agent rule with YAML frontmatter. |
+| `init-context skill <name>` | `init-context -s <name>` | Scaffolds a new agent skill directory with triggers & runbook. |
+| `init-context promote <name>` | — | Promotes local workspace rule/skill to Global Plugin & Central Memory. |
+| `init-context update` | — | Modular, non-breaking update for CLI, global plugin & system rules. |
+| `init-context share <name>` | — | Audits secrets and shares a rule or skill via GitHub Gist. |
+| `init-context import <url>` | — | Imports a rule or skill with 3-way Collision Guard protection. |
+| `init-context memory init` | — | Initializes private GitHub brain repository (`~/.auto-context/memory`). |
+| `init-context memory push` | — | Auto-harvests workspace rules, audits secrets & pushes to private GitHub. |
+| `init-context memory pull` | — | Pulls and restores central brain on a new machine. |
+| `init-context memory status` | — | Displays central brain location, remote URL, and rules/skills count. |
+| `init-context mcp add <name>`| `init-context --add-mcp` | Adds or updates an MCP tool (Node `npx` or Python `uvx`). |
+| `init-context mcp list` | `init-context --list-mcp` | Lists all active MCP server configurations. |
+| `init-context mcp remove <name>`| `init-context --remove-mcp` | Safely removes an MCP server configuration. |
+
+### Global Flags:
+* `-g, --global`: Targets machine-wide scope (`~/.gemini/config/plugins/auto-context/` & `~/.auto-context/memory/`).
+* `-f, --force`: Overwrites existing files (bypasses collision guards with confirmation).
+* `-d, --dry-run`: Previews actions without writing files or modifying directories.
+* `-v, --version`: Displays installed package version.
 
 ---
 
@@ -309,6 +297,68 @@ triggers: ["docker", "container", "compose", "dockerfile"]
 
 ---
 
+## 🚀 Rule Promotion & Auto-Harvesting (`init-context promote`)
+
+Sometimes a rule or workflow starts as a quick experiment in one project, but proves so valuable that you want every project across your machine and team to inherit it.
+
+### 1️⃣ 1-Command Rule Promotion
+```bash
+init-context promote docker-multi-stage
+```
+* **Elevates Local to Global:** Copies `.agents/rules/docker-multi-stage.md` directly into `~/.gemini/config/plugins/auto-context/rules/` and `~/.auto-context/memory/rules/`.
+* **Zero Rewriting:** Preserves all existing YAML frontmatter, guidelines, and constraints.
+* **Instant Sync:** Immediately run `init-context memory push` to backup the newly promoted rule to your private Git brain.
+
+### 2️⃣ Auto-Harvesting in Central Memory
+When you run:
+```bash
+init-context memory push
+```
+The CLI automatically:
+1. **Discovers Local Knowledge:** Scans the active workspace's `.agents/rules/` and `.agents/skills/`.
+2. **Harvests to Central Memory:** Copies any new rules and skills into `~/.auto-context/memory/` without overwriting existing files.
+3. **Audits Secrets:** Runs the Zero-Bypass security audit.
+4. **Pushes to Private Remote:** Backs up everything to your private GitHub repo.
+Even if an agent originally codified a rule locally, running `memory push` guarantees zero knowledge loss!
+
+---
+
+## 🛰️ Hub & Satellite Modular Architecture (< 400 Token Budget)
+
+Dumping routes, models, problem logs, credentials, and runbooks into a single monolithic `context.md` causes context file bloat (1,000–5,000 lines). Every turn burns thousands of unnecessary tokens simply reading the context file!
+
+Auto-Context solves this with the **Hub & Satellite Architecture**:
+
+```
+project-root/
+├── context.md                    <─── The Executive Hub (Capped at < 80 lines / ~400 tokens!)
+└── .agents/
+    └── context/                  <─── Stack-Adaptive Satellites (Loaded on-demand)
+        ├── routes.md             (API Endpoints & UI Page Map — loaded only for route tasks)
+        ├── schema.md             (Database Schemas & ORM Models — loaded only for DB tasks)
+        └── gotchas.md            (Critical Architecture Traps & Invariants)
+```
+
+### 1️⃣ Codebase Scanner (`init-context scan`)
+In any in-flight or 40% completed repository, run:
+```bash
+init-context scan
+```
+- **Zero Token Cost:** Scans project directories and manifests locally via fast filesystem heuristics (0 LLM tokens).
+- **Stack-Adaptive:**
+  - If Next.js / Express / FastAPI: Generates `.agents/context/routes.md`.
+  - If Prisma / Drizzle / Django / SQLAlchemy: Generates `.agents/context/schema.md`.
+  - Always provisions `.agents/context/gotchas.md`.
+- **Strict Idempotency Proof ($f(f(x)) = f(x)$):**
+  - Uses SHA-256 content hashes and anchored delimiters (`<!-- AUTO-CONTEXT:DISCOVERY:START -->`).
+  - Running `scan` 1 time or 100 times produces the exact same deterministic state without duplicating content.
+
+### 2️⃣ The Brutal Truth Filter & `gotchas.md`
+- **Zero Dead Logs:** A chronological diary of 50 minor solved bug typos is a waste of disk and token budget. Git already tracks commit history!
+- **Gotchas Over History:** Auto-Context replaces useless bug logs with **`gotchas.md`**: non-obvious architecture traps, port collisions, and invariants that cannot be guessed from reading code.
+
+---
+
 ## ⚡ Two-Tier Progressive Disclosure (Token-Optimized Architecture)
 
 To avoid context window bloat and burning 20k–30k tokens at session startup, Auto-Context enforces a **Two-Tier Progressive Disclosure Protocol**:
@@ -542,9 +592,34 @@ To prevent **Prompt Injection Leaks** and keep production secrets safe:
   init-context -s my-skill-name -g   # সকল প্রজেক্টের জন্য গ্লোবালি
   ```
 
+### 🛰️ হাব অ্যান্ড স্যাটেলাইট আর্কিটেকচার (< ৪০০ টোকেন সিলিং):
+সব রুট, ডাটাবেজ মডেল এবং হিস্ট্রি এক ফাইলে রাখলে `context.md` ১,০০০–৫,০০০ লাইন হয়ে টোকেন অপচয় করে। Auto-Context একে সমাধান করেছে **Hub & Satellite** মডেল দিয়ে:
+* **The Executive Hub (`context.md`):** প্রজেক্টের রুট ফাইল সবসময় সর্বোচ্চ **< ৮০ লাইন (< ৪০০ টোকেন)**-এ সীমাবদ্ধ থাকবে।
+* **স্ট্যাক-অ্যাডাপটিভ স্যাটেলাইট (`.agents/context/`):**
+  * `routes.md`: প্রজেক্টের এপিআই ও পেজ রুট ম্যাপ (শুধু রাউটিং কাজের সময় এআই পড়বে)।
+  * `schema.md`: ডাটাবেজ মডেল ও ওআরএম স্কিমা (শুধু ডাটাবেজ কাজের সময় পড়বে)।
+  * `gotchas.md`: বাস্তব টেকনিক্যাল ফাঁদ, পোর্ট কনফ্লিক্ট ও আর্কিটেকচারাল সীমাবদ্ধতা।
+
+### 🔍 কোডবেস স্ক্যানার (`init-context scan`):
+যেকোনো চলমান বা ৪০% শেষ হওয়া প্রজেক্টে টার্মিনালে রান করুন:
+```bash
+init-context scan
+```
+* **জিরো টোকেন খরচ:** সম্পূর্ণ অফলাইনে লোকাল প্রসেসর দিয়ে মাত্র ১০০ মিলিসেকেন্ডে প্রজেক্ট স্ক্যান করে স্যাটেলাইট ফাইল তৈরি করে।
+* **আইডেমপোটেন্সি প্রুফ ($f(f(x)) = f(x)$):** দিনে ১০০ বার কমান্ড চালালেও কোনো ডুপ্লিকেট কনটেন্ট হবে না বা ইউজারের নিজস্ব নোট ওভাররাইট হবে না।
+
 ### ⚡ টু-টায়ার প্রোগ্রেসিভ ডিসক্লোজার (টোকেন সাশ্রয়ী আর্কিটেকচার):
 শুরুতেই সব স্কিলের বড় ফাইল লোড করে চ্যাট ভারী করা হয় না। এআই শুরুতে মাত্র ১৫০–২০০ টোকেনের একটি ইনডেক্স (`context.md` Section 5) পড়ে। যখন নির্দিষ্ট টাস্কের কিওয়ার্ড মিলবে (যেমন: "docker", "rebase", "diagnostics", "ui test"), কেবল তখনই সংশ্লিষ্ট পূর্ণাঙ্গ স্কিলটি অন-ডিমান্ড মেমরিতে লোড হয়। ফলে টোকেন খরচ প্রায় ৮০% হ্রাস পায়!
 
+### 🚀 রুল প্রমোশন ও অটো-হার্ভেস্টিং (Promote & Auto-Harvest):
+* **লোকাল রুলকে গ্লোবালে উন্নীত করা (`promote`):**
+  যদি কোনো নির্দিষ্ট প্রজেক্টে তৈরি করা রুল বা স্কিল আপনার কম্পিউটারের সকল প্রজেক্টের জন্য প্রয়োজন হয়, তবে এক কমান্ডে গ্লোবাল প্লাগইন ও সেন্ট্রাল মেমরিতে প্রমোট করতে পারবেন:
+  ```bash
+  init-context promote docker-multi-stage
+  ```
+* **অটো-হার্ভেস্টিং (Auto-Harvesting in Memory Push):**
+  যখন আপনি `init-context memory push` চালাবেন, তখন বর্তমান প্রজেক্টের লোকাল রুল ও স্কিলগুলো স্বয়ংক্রিয়ভাবে সেন্ট্রাল মেমরিতে হার্ভেস্ট (সংগ্রহ) হবে এবং সিক্রেট অডিট পাস করে প্রাইভেট গিটহাবে ব্যাকআপ হয়ে যাবে।
+
 ### 🧠 সেন্ট্রাল মেমরি ব্রেইন ও ডটফাইলস (Disaster Recovery & Dotfiles):
 যেমনভাবে লিনাক্সে `.dotfiles` দিয়ে চোখের পলকে সব কনফিগারেশন সেটআপ করা যায়, তেমনি Auto-Context দিয়ে আপনার এআই এজেন্টের মেমরি ও স্কিল ক্লাউডে নিরাপদে সেভ থাকে:
 1. **প্রাইভেট মেমরি তৈরি (`memory init`):**

{auto_context_cli-1.0.2 → auto_context_cli-1.0.4}/README.md

@@ -6,7 +6,7 @@
 
 [![PyPI - Version](https://img.shields.io/pypi/v/auto-context-cli.svg?color=blue)](https://pypi.org/project/auto-context-cli/)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/auto-context-cli.svg)](https://pypi.org/project/auto-context-cli/)
-[![GitHub Release](https://img.shields.io/github/v/release/Cyber-arghya/auto-context?color=green)](https://github.com/Cyber-arghya/auto-context/releases/tag/v1.0.2)
+[![GitHub Release](https://img.shields.io/github/v/release/Cyber-arghya/auto-context?color=green)](https://github.com/Cyber-arghya/auto-context/releases/tag/v1.0.4)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux%20WSL2-success.svg)](#-quick-one-line-install)
 [![AI Supported](https://img.shields.io/badge/AI%20Supported-Antigravity%20%7C%20Cursor%20%7C%20Claude%20Code%20%7C%20Copilot%20%7C%20Windsurf-orange.svg)](#-supported-ai-assistants)
@@ -61,45 +61,33 @@ cd /path/to/any-project
 init-context
 ```
 
-### Options & Flags:
-```text
-init-context [OPTIONS] [DIRECTORY]
-
-OPTIONS (CONTEXT & RULES):
-  -r, --new-rule <NAME>     Scaffold a new rule file (.agents/rules/<name>.md)
-  -s, --new-skill <NAME>    Scaffold a new skill folder (.agents/skills/<name>/SKILL.md)
-  -g, --global              Target global plugin scope (~/.gemini/config/plugins/auto-context/)
-  -f, --force               Overwrite existing context.md and standing rule files
-  -d, --dry-run             Preview generated structure without writing to disk
-  -v, --version             Display current version
-  -h, --help                Show help documentation
-
-OPTIONS (CENTRAL MEMORY & GRANULAR SHARING):
-  memory init [REPO]        Initialize private central memory repo (~/.auto-context/memory)
-  memory push               Audit secrets & push memory brain to private GitHub repo
-  memory pull [URL]         Pull & sync central memory brain from remote repo
-  memory status             Show status of central memory brain
-  share <NAME>              Audit & publish skill or rule to GitHub Gist
-  import <URL>              Audit & import skill or rule from GitHub Gist or URL
-  update                    Safely update CLI, global plugin & public rules (Non-breaking)
-  update --check            Check for updates without modifying files
-  update -w, --workspace    Update managed system rules in active workspace
-  update -g, --global       Sync global plugin (~/.gemini/config/plugins/auto-context/)
-  update -c, --cli          Upgrade auto-context-cli package via uv/pipx/pip
-  --as <NAME>               Custom name when importing a skill or rule
-  --public                  Publish shared Gist as public (default)
-  --secret, --private       Publish shared Gist as unlisted/secret
-
-OPTIONS (MCP TOOLING):
-  --add-mcp <NAME>          Add or update an MCP server configuration
-  --remove-mcp <NAME>       Remove an MCP server from configuration
-  --list-mcp                List all active MCP server tools
-  --preset <PRESET>         Preset template (sqlite, postgres, github, filesystem, brave, fetch)
-  --command <CMD>           Executable command for stdio server (e.g. npx, uvx, python3)
-  --args <ARGS>             Arguments to pass to command
-  --url <URL>               Streamable HTTP endpoint URL for remote MCP server
-  --env <KEY=VAL,...>       Environment variables (e.g. 'GITHUB_TOKEN=xyz')
-```
+### Command Reference & Syntax:
+
+Auto-Context supports both modern subcommands (`init-context <command>`) and standard legacy flags:
+
+| Command | Shorthand / Flag | Description |
+| :--- | :--- | :--- |
+| `init-context init [DIR]` | `init-context [DIR]` | Scaffolds 5-tier context in active or specified directory. |
+| `init-context scan [DIR]` | `init-context --scan` | Stack-adaptive codebase scanner: generates satellites (.agents/context/). |
+| `init-context rule <name>` | `init-context -r <name>` | Scaffolds a new agent rule with YAML frontmatter. |
+| `init-context skill <name>` | `init-context -s <name>` | Scaffolds a new agent skill directory with triggers & runbook. |
+| `init-context promote <name>` | — | Promotes local workspace rule/skill to Global Plugin & Central Memory. |
+| `init-context update` | — | Modular, non-breaking update for CLI, global plugin & system rules. |
+| `init-context share <name>` | — | Audits secrets and shares a rule or skill via GitHub Gist. |
+| `init-context import <url>` | — | Imports a rule or skill with 3-way Collision Guard protection. |
+| `init-context memory init` | — | Initializes private GitHub brain repository (`~/.auto-context/memory`). |
+| `init-context memory push` | — | Auto-harvests workspace rules, audits secrets & pushes to private GitHub. |
+| `init-context memory pull` | — | Pulls and restores central brain on a new machine. |
+| `init-context memory status` | — | Displays central brain location, remote URL, and rules/skills count. |
+| `init-context mcp add <name>`| `init-context --add-mcp` | Adds or updates an MCP tool (Node `npx` or Python `uvx`). |
+| `init-context mcp list` | `init-context --list-mcp` | Lists all active MCP server configurations. |
+| `init-context mcp remove <name>`| `init-context --remove-mcp` | Safely removes an MCP server configuration. |
+
+### Global Flags:
+* `-g, --global`: Targets machine-wide scope (`~/.gemini/config/plugins/auto-context/` & `~/.auto-context/memory/`).
+* `-f, --force`: Overwrites existing files (bypasses collision guards with confirmation).
+* `-d, --dry-run`: Previews actions without writing files or modifying directories.
+* `-v, --version`: Displays installed package version.
 
 ---
 
@@ -295,6 +283,68 @@ triggers: ["docker", "container", "compose", "dockerfile"]
 
 ---
 
+## 🚀 Rule Promotion & Auto-Harvesting (`init-context promote`)
+
+Sometimes a rule or workflow starts as a quick experiment in one project, but proves so valuable that you want every project across your machine and team to inherit it.
+
+### 1️⃣ 1-Command Rule Promotion
+```bash
+init-context promote docker-multi-stage
+```
+* **Elevates Local to Global:** Copies `.agents/rules/docker-multi-stage.md` directly into `~/.gemini/config/plugins/auto-context/rules/` and `~/.auto-context/memory/rules/`.
+* **Zero Rewriting:** Preserves all existing YAML frontmatter, guidelines, and constraints.
+* **Instant Sync:** Immediately run `init-context memory push` to backup the newly promoted rule to your private Git brain.
+
+### 2️⃣ Auto-Harvesting in Central Memory
+When you run:
+```bash
+init-context memory push
+```
+The CLI automatically:
+1. **Discovers Local Knowledge:** Scans the active workspace's `.agents/rules/` and `.agents/skills/`.
+2. **Harvests to Central Memory:** Copies any new rules and skills into `~/.auto-context/memory/` without overwriting existing files.
+3. **Audits Secrets:** Runs the Zero-Bypass security audit.
+4. **Pushes to Private Remote:** Backs up everything to your private GitHub repo.
+Even if an agent originally codified a rule locally, running `memory push` guarantees zero knowledge loss!
+
+---
+
+## 🛰️ Hub & Satellite Modular Architecture (< 400 Token Budget)
+
+Dumping routes, models, problem logs, credentials, and runbooks into a single monolithic `context.md` causes context file bloat (1,000–5,000 lines). Every turn burns thousands of unnecessary tokens simply reading the context file!
+
+Auto-Context solves this with the **Hub & Satellite Architecture**:
+
+```
+project-root/
+├── context.md                    <─── The Executive Hub (Capped at < 80 lines / ~400 tokens!)
+└── .agents/
+    └── context/                  <─── Stack-Adaptive Satellites (Loaded on-demand)
+        ├── routes.md             (API Endpoints & UI Page Map — loaded only for route tasks)
+        ├── schema.md             (Database Schemas & ORM Models — loaded only for DB tasks)
+        └── gotchas.md            (Critical Architecture Traps & Invariants)
+```
+
+### 1️⃣ Codebase Scanner (`init-context scan`)
+In any in-flight or 40% completed repository, run:
+```bash
+init-context scan
+```
+- **Zero Token Cost:** Scans project directories and manifests locally via fast filesystem heuristics (0 LLM tokens).
+- **Stack-Adaptive:**
+  - If Next.js / Express / FastAPI: Generates `.agents/context/routes.md`.
+  - If Prisma / Drizzle / Django / SQLAlchemy: Generates `.agents/context/schema.md`.
+  - Always provisions `.agents/context/gotchas.md`.
+- **Strict Idempotency Proof ($f(f(x)) = f(x)$):**
+  - Uses SHA-256 content hashes and anchored delimiters (`<!-- AUTO-CONTEXT:DISCOVERY:START -->`).
+  - Running `scan` 1 time or 100 times produces the exact same deterministic state without duplicating content.
+
+### 2️⃣ The Brutal Truth Filter & `gotchas.md`
+- **Zero Dead Logs:** A chronological diary of 50 minor solved bug typos is a waste of disk and token budget. Git already tracks commit history!
+- **Gotchas Over History:** Auto-Context replaces useless bug logs with **`gotchas.md`**: non-obvious architecture traps, port collisions, and invariants that cannot be guessed from reading code.
+
+---
+
 ## ⚡ Two-Tier Progressive Disclosure (Token-Optimized Architecture)
 
 To avoid context window bloat and burning 20k–30k tokens at session startup, Auto-Context enforces a **Two-Tier Progressive Disclosure Protocol**:
@@ -528,9 +578,34 @@ To prevent **Prompt Injection Leaks** and keep production secrets safe:
   init-context -s my-skill-name -g   # সকল প্রজেক্টের জন্য গ্লোবালি
   ```
 
+### 🛰️ হাব অ্যান্ড স্যাটেলাইট আর্কিটেকচার (< ৪০০ টোকেন সিলিং):
+সব রুট, ডাটাবেজ মডেল এবং হিস্ট্রি এক ফাইলে রাখলে `context.md` ১,০০০–৫,০০০ লাইন হয়ে টোকেন অপচয় করে। Auto-Context একে সমাধান করেছে **Hub & Satellite** মডেল দিয়ে:
+* **The Executive Hub (`context.md`):** প্রজেক্টের রুট ফাইল সবসময় সর্বোচ্চ **< ৮০ লাইন (< ৪০০ টোকেন)**-এ সীমাবদ্ধ থাকবে।
+* **স্ট্যাক-অ্যাডাপটিভ স্যাটেলাইট (`.agents/context/`):**
+  * `routes.md`: প্রজেক্টের এপিআই ও পেজ রুট ম্যাপ (শুধু রাউটিং কাজের সময় এআই পড়বে)।
+  * `schema.md`: ডাটাবেজ মডেল ও ওআরএম স্কিমা (শুধু ডাটাবেজ কাজের সময় পড়বে)।
+  * `gotchas.md`: বাস্তব টেকনিক্যাল ফাঁদ, পোর্ট কনফ্লিক্ট ও আর্কিটেকচারাল সীমাবদ্ধতা।
+
+### 🔍 কোডবেস স্ক্যানার (`init-context scan`):
+যেকোনো চলমান বা ৪০% শেষ হওয়া প্রজেক্টে টার্মিনালে রান করুন:
+```bash
+init-context scan
+```
+* **জিরো টোকেন খরচ:** সম্পূর্ণ অফলাইনে লোকাল প্রসেসর দিয়ে মাত্র ১০০ মিলিসেকেন্ডে প্রজেক্ট স্ক্যান করে স্যাটেলাইট ফাইল তৈরি করে।
+* **আইডেমপোটেন্সি প্রুফ ($f(f(x)) = f(x)$):** দিনে ১০০ বার কমান্ড চালালেও কোনো ডুপ্লিকেট কনটেন্ট হবে না বা ইউজারের নিজস্ব নোট ওভাররাইট হবে না।
+
 ### ⚡ টু-টায়ার প্রোগ্রেসিভ ডিসক্লোজার (টোকেন সাশ্রয়ী আর্কিটেকচার):
 শুরুতেই সব স্কিলের বড় ফাইল লোড করে চ্যাট ভারী করা হয় না। এআই শুরুতে মাত্র ১৫০–২০০ টোকেনের একটি ইনডেক্স (`context.md` Section 5) পড়ে। যখন নির্দিষ্ট টাস্কের কিওয়ার্ড মিলবে (যেমন: "docker", "rebase", "diagnostics", "ui test"), কেবল তখনই সংশ্লিষ্ট পূর্ণাঙ্গ স্কিলটি অন-ডিমান্ড মেমরিতে লোড হয়। ফলে টোকেন খরচ প্রায় ৮০% হ্রাস পায়!
 
+### 🚀 রুল প্রমোশন ও অটো-হার্ভেস্টিং (Promote & Auto-Harvest):
+* **লোকাল রুলকে গ্লোবালে উন্নীত করা (`promote`):**
+  যদি কোনো নির্দিষ্ট প্রজেক্টে তৈরি করা রুল বা স্কিল আপনার কম্পিউটারের সকল প্রজেক্টের জন্য প্রয়োজন হয়, তবে এক কমান্ডে গ্লোবাল প্লাগইন ও সেন্ট্রাল মেমরিতে প্রমোট করতে পারবেন:
+  ```bash
+  init-context promote docker-multi-stage
+  ```
+* **অটো-হার্ভেস্টিং (Auto-Harvesting in Memory Push):**
+  যখন আপনি `init-context memory push` চালাবেন, তখন বর্তমান প্রজেক্টের লোকাল রুল ও স্কিলগুলো স্বয়ংক্রিয়ভাবে সেন্ট্রাল মেমরিতে হার্ভেস্ট (সংগ্রহ) হবে এবং সিক্রেট অডিট পাস করে প্রাইভেট গিটহাবে ব্যাকআপ হয়ে যাবে।
+
 ### 🧠 সেন্ট্রাল মেমরি ব্রেইন ও ডটফাইলস (Disaster Recovery & Dotfiles):
 যেমনভাবে লিনাক্সে `.dotfiles` দিয়ে চোখের পলকে সব কনফিগারেশন সেটআপ করা যায়, তেমনি Auto-Context দিয়ে আপনার এআই এজেন্টের মেমরি ও স্কিল ক্লাউডে নিরাপদে সেভ থাকে:
 1. **প্রাইভেট মেমরি তৈরি (`memory init`):**

{auto_context_cli-1.0.2 → auto_context_cli-1.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "auto-context-cli"
-version = "1.0.2"
+version = "1.0.4"
 description = "Autonomous context & instruction manager for AI coding assistants"
 readme = "README.md"
 requires-python = ">=3.11"

{auto_context_cli-1.0.2 → auto_context_cli-1.0.4}/src/auto_context/__init__.py

@@ -1,3 +1,3 @@
 """auto-context: Autonomous context & instruction manager for AI coding assistants."""
 
-__version__ = "1.0.2"
+__version__ = "1.0.4"

{auto_context_cli-1.0.2 → auto_context_cli-1.0.4}/src/auto_context/commands/init_cmd.py

@@ -207,6 +207,13 @@ def init(
             ".env.*.local",
         ])
 
+        # ── Stack-Adaptive Satellites (.agents/context/) ───────────────────────
+        try:
+            from auto_context import scanner
+            scanner.generate_satellites(project_dir, force=force)
+        except Exception:
+            pass
+
     console.print(Panel(
         "[bold green]✨ Project scaffold complete![/]\n"
         "Edit [cyan]context.md[/] and [cyan]GEMINI.md[/] to customise your AI workspace.",

auto_context_cli-1.0.4/src/auto_context/commands/scan_cmd.py

@@ -0,0 +1,134 @@
+"""
+scan_cmd.py — On-demand codebase inspection and satellite synchronization command.
+
+Discovers routes, data models, network ports, and runbooks without burning LLM tokens.
+Generates or updates stack-adaptive satellites (.agents/context/) and synchronizes
+the Executive Hub (context.md) with strict idempotency and hash verification.
+"""
+from datetime import date
+from pathlib import Path
+from typing import Annotated, Optional
+
+from rich.console import Console
+from rich.panel import Panel
+import typer
+
+from auto_context import scanner
+from auto_context.commands import init_cmd
+
+console = Console()
+
+
+def scan(
+    target: Annotated[Optional[Path], typer.Argument(help="Target project directory.")] = None,
+    force: Annotated[bool, typer.Option("--force", "-f", help="Force overwrite satellite files.")] = False,
+) -> None:
+    """
+    Inspect project codebase, generate stack-adaptive satellites, and sync context.md.
+
+    Zero Token Cost:
+    - Runs 100% locally via fast filesystem heuristics.
+    - Generates .agents/context/routes.md, schema.md, gotchas.md as needed.
+    - Keeps primary context.md compact (< 400 tokens) using the Hub & Satellite pattern.
+    """
+    project_dir = (target or Path.cwd()).resolve()
+    project_name = project_dir.name
+    stack, framework = init_cmd.detect_stack(project_dir)
+
+    console.print(Panel(
+        f"[bold cyan]🔍 Auto-Context: Stack-Adaptive Codebase Scanner[/]\n"
+        f"[yellow]   Target:[/] {project_name} ({project_dir})\n"
+        f"[cyan]   Stack: [/] {stack} ([dim]{framework}[/])",
+        border_style="cyan",
+    ))
+
+    # 1. Discover ports & services
+    ports = scanner.discover_ports_and_services(project_dir)
+    # 2. Discover runbook commands
+    commands = scanner.discover_runbook_commands(project_dir)
+    # 3. Generate adaptive satellites in .agents/context/
+    satellites = scanner.generate_satellites(project_dir, force=force)
+
+    # 4. Render/Sync the compact Executive Hub (context.md)
+    hub_file = project_dir / "context.md"
+    date_now = date.today().isoformat()
+
+    # Build discovered ports table
+    ports_table = "| Service / Key | Port | Source |\n| :--- | :--- | :--- |\n"
+    if ports:
+        for svc, port, src in ports:
+            ports_table += f"| **{svc}** | `{port}` | {src} |\n"
+    else:
+        ports_table += "| **App Port** | `3000` (Default) | Inferred |\n"
+
+    # Build runbook table
+    runbook_table = "| Task | Executable Command |\n| :--- | :--- |\n"
+    if commands:
+        for action, cmd in commands:
+            runbook_table += f"| {action} | `{cmd}` |\n"
+    else:
+        runbook_table += "| Start Development | `npm run dev` / `python main.py` |\n"
+
+    # Build satellites index section
+    satellites_index = ""
+    if "routes" in satellites:
+        satellites_index += f"- **Route Map:** [`routes.md`](file://{satellites['routes'].as_posix()})\n"
+    if "schema" in satellites:
+        satellites_index += f"- **Database Schemas:** [`schema.md`](file://{satellites['schema'].as_posix()})\n"
+    if "gotchas" in satellites:
+        satellites_index += f"- **Critical Gotchas:** [`gotchas.md`](file://{satellites['gotchas'].as_posix()})\n"
+
+    # Anchored block for idempotent synchronization
+    anchored_block = (
+        "<!-- AUTO-CONTEXT:DISCOVERY:START -->\n"
+        "## 1. Discovered Ports & Network Vault\n\n"
+        f"{ports_table}\n"
+        "## 2. Stack & Adaptive Satellites\n\n"
+        f"* **Stack:** {stack} ({framework})\n"
+        f"{satellites_index if satellites_index else '- Satellites: Core stack (no external routes/models detected)\n'}\n"
+        "## 3. Operations Runbook\n\n"
+        f"{runbook_table}\n"
+        "<!-- AUTO-CONTEXT:DISCOVERY:END -->"
+    )
+
+    if hub_file.exists():
+        existing_text = hub_file.read_text(encoding="utf-8")
+        if "<!-- AUTO-CONTEXT:DISCOVERY:START -->" in existing_text:
+            # Idempotent replacement of discovery block
+            pattern = r"<!-- AUTO-CONTEXT:DISCOVERY:START -->.*?<!-- AUTO-CONTEXT:DISCOVERY:END -->"
+            import re
+            new_hub_text = re.sub(pattern, anchored_block, existing_text, flags=re.DOTALL)
+        else:
+            # Upgrade existing legacy context.md by prepending hub block
+            new_hub_text = (
+                f"# {project_name} — Executive Context Hub\n\n"
+                f"> **Last Updated:** {date_now} | **Stack:** {stack} ({framework})\n\n"
+                f"{anchored_block}\n\n"
+                "## 4. Active Invariants & Gotchas\n\n"
+                "See [`.agents/context/gotchas.md`](file://"
+                f"{(project_dir / '.agents' / 'context' / 'gotchas.md').as_posix()}) "
+                "for institutional knowledge.\n"
+            )
+    else:
+        # Create brand new Executive Hub (< 60 lines!)
+        new_hub_text = (
+            f"# {project_name} — Executive Context Hub\n\n"
+            f"> **Last Updated:** {date_now} | **Stack:** {stack} ({framework})\n\n"
+            f"{anchored_block}\n\n"
+            "## 4. Active Invariants & Gotchas\n\n"
+            "Inspect [`.agents/context/gotchas.md`](file://"
+            f"{(project_dir / '.agents' / 'context' / 'gotchas.md').as_posix()}) "
+            "before modifying architecture.\n"
+        )
+
+    scanner.write_idempotent(hub_file, new_hub_text, "Executive Hub (context.md)")
+
+    console.print(Panel(
+        f"[bold green]✨ Codebase scan completed with zero token waste![/]\n"
+        f"[white]• Ports discovered:      [green]{len(ports)}[/]\n"
+        f"• Runbook commands:      [green]{len(commands)}[/]\n"
+        f"• Satellites generated:  [green]{len(satellites)}[/] (routes, schema, gotchas)\n"
+        f"• Hub size (context.md): [bold green]< 60 lines (Token Optimized)[/]",
+        border_style="green",
+    ))
+

{auto_context_cli-1.0.2 → auto_context_cli-1.0.4}/src/auto_context/main.py

@@ -11,7 +11,7 @@ from typing import Annotated, Optional
 import typer
 from rich.console import Console
 
-from auto_context.commands import init_cmd, memory, mcp, share, import_cmd, update_cmd
+from auto_context.commands import init_cmd, memory, mcp, share, import_cmd, update_cmd, scan_cmd
 
 app = typer.Typer(
     name="init-context",
@@ -33,6 +33,7 @@ app.command("promote")(init_cmd.promote)
 app.command("share")(share.share)
 app.command("import")(import_cmd.import_item)
 app.command("update")(update_cmd.update)
+app.command("scan")(scan_cmd.scan)
 
 
 @app.callback(invoke_without_command=True)
@@ -54,6 +55,7 @@ def root(
     global_: Annotated[bool, typer.Option("--global", "-g", help="Target global plugin scope.")] = False,
     force: Annotated[bool, typer.Option("--force", "-f", help="Overwrite existing files.")] = False,
     dry_run: Annotated[bool, typer.Option("--dry-run", "-d", help="Preview without writing.")] = False,
+    scan: Annotated[bool, typer.Option("--scan", help="Run stack-adaptive scanner on target directory.")] = False,
     version: bool = typer.Option(False, "--version", "-v", help="Show version and exit."),
 ) -> None:
     """
@@ -67,7 +69,7 @@ def root(
             try:
                 v = pkg_version("auto-context")
             except Exception:
-                v = "1.0.1"
+                v = "1.0.4"
         console.print(f"init-context v{v}")
         raise typer.Exit()
 
@@ -106,6 +108,10 @@ def root(
         )
         return
 
+    if scan:
+        scan_cmd.scan(target=target, force=force)
+        return
+
     # Default action: scaffold workspace
     init_cmd.init(target=target, force=force, dry_run=dry_run)