auto-context-cli 1.0.1__tar.gz → 1.0.3__tar.gz

{auto_context_cli-1.0.1 → auto_context_cli-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: auto-context-cli
-Version: 1.0.1
+Version: 1.0.3
 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.1)
+[![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.3)
 [![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,40 +75,65 @@ cd /path/to/any-project
 init-context
 ```
 
-### Options & Flags:
+### 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.
+
+---
+
+## 🔄 Modular Upstream Sync & Non-Breaking Updates (আপডেট ও সিঙ্ক)
+
+When new public rules, skills, or agent capabilities are added to the official [Cyber-arghya/auto-context](https://github.com/Cyber-arghya/auto-context) repository:
+
+### 1️⃣ Automatic Background Notification
+`auto-context` includes a lightweight, cached (24h TTL) update notifier. Whenever you or an AI agent runs `init-context`, it unobtrusively checks PyPI and GitHub. If new upstream rules or versions are available, a clean banner is displayed:
 ```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
-  --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')
+╭─────────────────────────────────────────────────────────────────────────────╮
+│ 🔔 Auto-Context Update Available: v1.0.1 → v1.0.2                           │
+│    New public rules, skills, and upstream capabilities are ready.           │
+│    Run 'init-context update' to sync modularly without breaking local context.│
+╰─────────────────────────────────────────────────────────────────────────────╯
+```
+
+### 2️⃣ 1-Command Safe Modular Update
+Run:
+```bash
+init-context update
 ```
+- **Upgrades CLI Package:** Automatically updates `auto-context-cli` via `uv tool`, `pipx`, or `pip`.
+- **Syncs Global Plugin:** Updates `~/.gemini/config/plugins/auto-context/` (`rules/AGENTS.md`, `skills/auto-context/SKILL.md`) with upstream instructions.
+- **Syncs Workspace System Rules:** Updates system rules (`.agents/rules/maintain_context.md`, `AGENTS.md`, `GEMINI.md`).
+
+> [!TIP]
+> **Strict Non-Breaking Guarantees:**
+> - **Zero Context Loss:** `context.md` is **NEVER** modified or overwritten. All project credentials, architecture diagrams, and problem history remain 100% intact.
+> - **Secret Protection:** `context.local.md`, `.env`, and test logins are **NEVER** touched.
+> - **Custom Rule Safety:** Your personal rules (e.g. `docker-multi-stage.md`, `my-style.md`) are **NEVER** overwritten or deleted.
+> - **Automatic Backup:** If you customized `AGENTS.md`, the updater automatically creates an `AGENTS.md.bak` backup.
 
 ---
 
@@ -272,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**:
@@ -505,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`):**
@@ -537,6 +649,20 @@ To prevent **Prompt Injection Leaks** and keep production secrets safe:
   ```
   > **কলিশন গার্ড:** যদি একই নামের কোনো স্কিল আগে থেকেই থেকে থাকে, তবে এটি না জানিয়ে কখনো ওভাররাইট করবে না। টার্মিনালে আপনাকে ৩টি অপশন দেবে: `[O]verwrite / [R]ename / [C]ancel`।
 
+### 🔄 মডুলার আপস্ট্রিম আপডেট ও স্বয়ংক্রিয় নোটিফিকেশন (Update & Sync):
+অফিশিয়াল গিটহাব রিপোজিটরিতে নতুন কোনো রুলবুক, স্কিল বা এআই এজেন্ট টুল যুক্ত হলে ব্যবহারকারীরা খুব সহজে আপডেট পেতে পারেন:
+1. **স্বয়ংক্রিয় নোটিফিকেশন ব্যানার:** চব্বিশ ঘণ্টায় একবার ব্যাকগ্রাউন্ডে চেক করে নতুন রুল আসলে টার্মিনালে সুন্দর নোটিফিকেশন দেখাবে।
+2. **এক কমান্ডে নিরাপদ আপডেট (`init-context update`):**
+   ```bash
+   init-context update           # ফুল মডুলার আপডেট (CLI + গ্লোবাল প্লাগইন + সিস্টেম রুলস)
+   init-context update --check   # কোনো আপডেট আছে কিনা শুধু চেক করতে
+   init-context update -w        # শুধুমাত্র বর্তমান প্রজেক্টের সিস্টেম রুলস আপডেট করতে
+   ```
+> **ব্রেকিং-চেঞ্জ মুক্ত সুরক্ষা (Zero Breaking Guarantee):**
+> * আপনার প্রজেক্টের `context.md`, `context.local.md` বা `.env` ফাইলে **কখনোই হাত দেওয়া হবে না**।
+> * আপনার তৈরিকৃত কোনো কাস্টম রুল মুছে যাবে না।
+> * কোনো ফাইলে কাস্টম পরিবর্তন থাকলে স্বয়ংক্রিয়ভাবে `.bak` ব্যাকআপ তৈরি হবে।
+
 ### নিরাপদ MCP টুল ম্যানেজমেন্ট (Secure Secrets via .env):
 টোকেন বা পাসওয়ার্ড কখনোই কনফিগ ফাইলে ওপেন টেক্সটে সেভ হয় না, বরং `.env` এবং `.gitignore`-এর মাধ্যমে নিরাপদ থাকে:
 * **টুল যুক্ত করতে (Node `npx` বা Python `uvx` সাপোর্ট):**

{auto_context_cli-1.0.1 → auto_context_cli-1.0.3}/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.1)
+[![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.3)
 [![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,40 +61,65 @@ cd /path/to/any-project
 init-context
 ```
 
-### Options & Flags:
+### 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.
+
+---
+
+## 🔄 Modular Upstream Sync & Non-Breaking Updates (আপডেট ও সিঙ্ক)
+
+When new public rules, skills, or agent capabilities are added to the official [Cyber-arghya/auto-context](https://github.com/Cyber-arghya/auto-context) repository:
+
+### 1️⃣ Automatic Background Notification
+`auto-context` includes a lightweight, cached (24h TTL) update notifier. Whenever you or an AI agent runs `init-context`, it unobtrusively checks PyPI and GitHub. If new upstream rules or versions are available, a clean banner is displayed:
 ```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
-  --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')
+╭─────────────────────────────────────────────────────────────────────────────╮
+│ 🔔 Auto-Context Update Available: v1.0.1 → v1.0.2                           │
+│    New public rules, skills, and upstream capabilities are ready.           │
+│    Run 'init-context update' to sync modularly without breaking local context.│
+╰─────────────────────────────────────────────────────────────────────────────╯
+```
+
+### 2️⃣ 1-Command Safe Modular Update
+Run:
+```bash
+init-context update
 ```
+- **Upgrades CLI Package:** Automatically updates `auto-context-cli` via `uv tool`, `pipx`, or `pip`.
+- **Syncs Global Plugin:** Updates `~/.gemini/config/plugins/auto-context/` (`rules/AGENTS.md`, `skills/auto-context/SKILL.md`) with upstream instructions.
+- **Syncs Workspace System Rules:** Updates system rules (`.agents/rules/maintain_context.md`, `AGENTS.md`, `GEMINI.md`).
+
+> [!TIP]
+> **Strict Non-Breaking Guarantees:**
+> - **Zero Context Loss:** `context.md` is **NEVER** modified or overwritten. All project credentials, architecture diagrams, and problem history remain 100% intact.
+> - **Secret Protection:** `context.local.md`, `.env`, and test logins are **NEVER** touched.
+> - **Custom Rule Safety:** Your personal rules (e.g. `docker-multi-stage.md`, `my-style.md`) are **NEVER** overwritten or deleted.
+> - **Automatic Backup:** If you customized `AGENTS.md`, the updater automatically creates an `AGENTS.md.bak` backup.
 
 ---
 
@@ -258,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**:
@@ -491,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`):**
@@ -523,6 +635,20 @@ To prevent **Prompt Injection Leaks** and keep production secrets safe:
   ```
   > **কলিশন গার্ড:** যদি একই নামের কোনো স্কিল আগে থেকেই থেকে থাকে, তবে এটি না জানিয়ে কখনো ওভাররাইট করবে না। টার্মিনালে আপনাকে ৩টি অপশন দেবে: `[O]verwrite / [R]ename / [C]ancel`।
 
+### 🔄 মডুলার আপস্ট্রিম আপডেট ও স্বয়ংক্রিয় নোটিফিকেশন (Update & Sync):
+অফিশিয়াল গিটহাব রিপোজিটরিতে নতুন কোনো রুলবুক, স্কিল বা এআই এজেন্ট টুল যুক্ত হলে ব্যবহারকারীরা খুব সহজে আপডেট পেতে পারেন:
+1. **স্বয়ংক্রিয় নোটিফিকেশন ব্যানার:** চব্বিশ ঘণ্টায় একবার ব্যাকগ্রাউন্ডে চেক করে নতুন রুল আসলে টার্মিনালে সুন্দর নোটিফিকেশন দেখাবে।
+2. **এক কমান্ডে নিরাপদ আপডেট (`init-context update`):**
+   ```bash
+   init-context update           # ফুল মডুলার আপডেট (CLI + গ্লোবাল প্লাগইন + সিস্টেম রুলস)
+   init-context update --check   # কোনো আপডেট আছে কিনা শুধু চেক করতে
+   init-context update -w        # শুধুমাত্র বর্তমান প্রজেক্টের সিস্টেম রুলস আপডেট করতে
+   ```
+> **ব্রেকিং-চেঞ্জ মুক্ত সুরক্ষা (Zero Breaking Guarantee):**
+> * আপনার প্রজেক্টের `context.md`, `context.local.md` বা `.env` ফাইলে **কখনোই হাত দেওয়া হবে না**।
+> * আপনার তৈরিকৃত কোনো কাস্টম রুল মুছে যাবে না।
+> * কোনো ফাইলে কাস্টম পরিবর্তন থাকলে স্বয়ংক্রিয়ভাবে `.bak` ব্যাকআপ তৈরি হবে।
+
 ### নিরাপদ MCP টুল ম্যানেজমেন্ট (Secure Secrets via .env):
 টোকেন বা পাসওয়ার্ড কখনোই কনফিগ ফাইলে ওপেন টেক্সটে সেভ হয় না, বরং `.env` এবং `.gitignore`-এর মাধ্যমে নিরাপদ থাকে:
 * **টুল যুক্ত করতে (Node `npx` বা Python `uvx` সাপোর্ট):**

{auto_context_cli-1.0.1 → auto_context_cli-1.0.3}/pyproject.toml

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

{auto_context_cli-1.0.1 → auto_context_cli-1.0.3}/src/auto_context/__init__.py

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

{auto_context_cli-1.0.1 → auto_context_cli-1.0.3}/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.",