PyPI - auto-context-cli - Versions diffs - 1.0.2__tar.gz → 1.0.3__tar.gz - Mend

auto-context-cli 1.0.2tar.gz → 1.0.3tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (36) hide show

{auto_context_cli-1.0.2 → auto_context_cli-1.0.3}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: auto-context-cli
-Version: 1.0.2
+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.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.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,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.3}/README.md RENAMED Viewed

@@ -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.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,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.3}/pyproject.toml RENAMED Viewed

@@ -1,6 +1,6 @@
 [project]
 name = "auto-context-cli"
-version = "1.0.2"
+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.2 → auto_context_cli-1.0.3}/src/auto_context/__init__.py RENAMED Viewed

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

{auto_context_cli-1.0.2 → auto_context_cli-1.0.3}/src/auto_context/commands/init_cmd.py RENAMED Viewed

@@ -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.3/src/auto_context/commands/scan_cmd.py ADDED Viewed

@@ -0,0 +1,133 @@
+"""
+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.3}/src/auto_context/main.py RENAMED Viewed

@@ -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.3"
         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)

auto_context_cli-1.0.3/src/auto_context/scanner.py ADDED Viewed

@@ -0,0 +1,297 @@
+"""
+scanner.py — Stack-Adaptive Codebase Introspection & Brownfield Discovery Engine.
+Discovers ports, routes, database schemas, services, and runbooks using lightweight
+filesystem convention heuristics (0 LLM tokens, 100% crash-proof, idempotency-guaranteed).
+"""
+import hashlib
+import json
+from pathlib import Path
+import re
+from typing import Optional
+from rich.console import Console
+console = Console()
+# ── Idempotency & Hash Helpers ────────────────────────────────────────────────
+def get_content_hash(text: str) -> str:
+    """Compute SHA-256 hash of text content."""
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+def write_idempotent(path: Path, content: str, label: str = "File") -> bool:
+    """
+    Write content to path only if content has changed (Content-Hash Guard).
+    Returns True if a write occurred, False if content was already identical.
+    """
+    if path.exists():
+        try:
+            existing = path.read_text(encoding="utf-8")
+            if get_content_hash(existing) == get_content_hash(content):
+                console.print(f"  [dim]— Up to date:[/] {path.name}")
+                return False
+        except Exception:
+            pass
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    console.print(f"  [green][✓] Synchronized:[/] {path.name}")
+    return True
+# ── Port & Service Extractor ──────────────────────────────────────────────────
+def discover_ports_and_services(project_dir: Path) -> list[tuple[str, str, str]]:
+    """
+    Extract network ports and service bindings from configs without leaking secrets.
+    Returns list of (Service, Port, SourceFile).
+    """
+    results: list[tuple[str, str, str]] = []
+    seen_ports: set[str] = set()
+    # 1. Check docker-compose.yml / compose.yaml
+    for compose_name in ("docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml"):
+        compose_file = project_dir / compose_name
+        if compose_file.exists():
+            try:
+                text = compose_file.read_text(encoding="utf-8", errors="ignore")
+                matches = re.findall(r'["\']?(\d{2,5}):(\d{2,5})["\']?', text)
+                for host_port, container_port in matches:
+                    if host_port not in seen_ports and int(host_port) > 80:
+                        seen_ports.add(host_port)
+                        results.append(("Container Port", host_port, compose_name))
+            except Exception:
+                pass
+    # 2. Check .env.example / .env
+    for env_name in (".env.example", ".env", ".env.local"):
+        env_file = project_dir / env_name
+        if env_file.exists():
+            try:
+                for line in env_file.read_text(encoding="utf-8", errors="ignore").splitlines():
+                    line = line.strip()
+                    if line.startswith("#") or "=" not in line:
+                        continue
+                    key, val = line.split("=", 1)
+                    key = key.strip()
+                    val = val.strip().strip('"').strip("'")
+                    if "PORT" in key.upper() and val.isdigit() and val not in seen_ports:
+                        seen_ports.add(val)
+                        results.append((key, val, env_name))
+            except Exception:
+                pass
+    # 3. Check Dockerfile
+    dockerfile = project_dir / "Dockerfile"
+    if dockerfile.exists():
+        try:
+            for line in dockerfile.read_text(encoding="utf-8", errors="ignore").splitlines():
+                if line.strip().upper().startswith("EXPOSE "):
+                    port = line.strip().split()[1]
+                    if port.isdigit() and port not in seen_ports:
+                        seen_ports.add(port)
+                        results.append(("Exposed Port", port, "Dockerfile"))
+        except Exception:
+            pass
+    return results
+# ── Runbook Command Extractor ─────────────────────────────────────────────────
+def discover_runbook_commands(project_dir: Path) -> list[tuple[str, str]]:
+    """
+    Extract executable development, build, and test commands from project manifests.
+    Returns list of (Action, Command).
+    """
+    commands: list[tuple[str, str]] = []
+    # 1. package.json scripts
+    pkg_file = project_dir / "package.json"
+    if pkg_file.exists():
+        try:
+            data = json.loads(pkg_file.read_text(encoding="utf-8", errors="ignore"))
+            scripts = data.get("scripts", {})
+            for key in ("dev", "start", "build", "test", "lint"):
+                if key in scripts:
+                    commands.append((f"Run {key}", f"npm run {key}"))
+        except Exception:
+            pass
+    # 2. Makefile
+    makefile = project_dir / "Makefile"
+    if makefile.exists():
+        try:
+            targets = re.findall(r"^([a-zA-Z0-9_-]+):", makefile.read_text(encoding="utf-8", errors="ignore"), re.M)
+            for t in targets[:4]:
+                if not t.startswith("."):
+                    commands.append((f"Make {t}", f"make {t}"))
+        except Exception:
+            pass
+    # 3. Python indicators
+    if (project_dir / "manage.py").exists():
+        commands.append(("Django Runserver", "python manage.py runserver"))
+        commands.append(("Django Migrate", "python manage.py migrate"))
+    elif (project_dir / "pyproject.toml").exists() or (project_dir / "requirements.txt").exists():
+        for main_candidate in ("main.py", "app.py", "server.py", "wsgi.py"):
+            if (project_dir / main_candidate).exists():
+                commands.append(("Start Python Server", f"python {main_candidate}"))
+                break
+    # 4. Docker Compose
+    if (project_dir / "docker-compose.yml").exists() or (project_dir / "compose.yaml").exists():
+        commands.append(("Start Docker Services", "docker compose up -d"))
+    return commands
+# ── Routes & Endpoints Extractor ──────────────────────────────────────────────
+def discover_routes(project_dir: Path) -> list[str]:
+    """
+    Extract API and UI routes using Next.js, Express, FastAPI, and Django conventions.
+    Returns clean list of detected route paths.
+    """
+    routes: list[str] = []
+    try:
+        # 1. Next.js App Router (app/ or src/app/)
+        app_dirs = [d for d in (project_dir / "app", project_dir / "src" / "app") if d.is_dir()]
+        for app_dir in app_dirs:
+            for file_path in app_dir.rglob("*"):
+                if file_path.is_file() and file_path.name in ("route.ts", "route.js", "page.tsx", "page.jsx"):
+                    rel = file_path.parent.relative_to(app_dir).as_posix()
+                    route_path = "/" if rel == "." else f"/{rel}"
+                    kind = "API" if file_path.name.startswith("route") else "Page"
+                    routes.append(f"[{kind}] {route_path} -> {file_path.relative_to(project_dir).as_posix()}")
+        # 2. Next.js Pages Router (pages/ or src/pages/)
+        page_dirs = [d for d in (project_dir / "pages", project_dir / "src" / "pages") if d.is_dir()]
+        for page_dir in page_dirs:
+            for file_path in page_dir.rglob("*.tsx"):
+                if not file_path.name.startswith("_"):
+                    rel = file_path.relative_to(page_dir).with_suffix("").as_posix()
+                    route_path = "/" if rel == "index" else f"/{rel.replace('/index', '')}"
+                    kind = "API" if "api" in rel else "Page"
+                    routes.append(f"[{kind}] {route_path} -> {file_path.relative_to(project_dir).as_posix()}")
+        # 3. Express / FastAPI / Django Route folders
+        for folder_name in ("routes", "controllers", "routers", "endpoints"):
+            for candidate in (project_dir / folder_name, project_dir / "src" / folder_name):
+                if candidate.is_dir():
+                    for f in candidate.glob("*.py") if candidate.glob("*.py") else candidate.glob("*.ts"):
+                        routes.append(f"[Module] {f.stem} -> {f.relative_to(project_dir).as_posix()}")
+    except Exception:
+        pass
+    return routes[:35]  # Cap to prevent unbounded lists
+# ── Database Models Extractor ─────────────────────────────────────────────────
+def discover_database_models(project_dir: Path) -> list[str]:
+    """
+    Extract data models from Prisma, Django, SQLAlchemy, Drizzle schemas.
+    Returns list of discovered model names and schema files.
+    """
+    models: list[str] = []
+    try:
+        # 1. Prisma schema
+        for prisma_path in (project_dir / "prisma" / "schema.prisma", project_dir / "schema.prisma"):
+            if prisma_path.exists():
+                text = prisma_path.read_text(encoding="utf-8", errors="ignore")
+                found = re.findall(r"\bmodel\s+([A-Za-z0-9_]+)\s*\{", text)
+                for m in found:
+                    models.append(f"[Prisma] {m} ({prisma_path.relative_to(project_dir).as_posix()})")
+        # 2. Django / SQLAlchemy models.py
+        for models_file in project_dir.rglob("models.py"):
+            if "venv" not in models_file.parts and ".git" not in models_file.parts:
+                text = models_file.read_text(encoding="utf-8", errors="ignore")
+                found = re.findall(r"\bclass\s+([A-Za-z0-9_]+)\s*\(", text)
+                for m in found:
+                    if m not in ("Meta",):
+                        models.append(f"[Model] {m} ({models_file.relative_to(project_dir).as_posix()})")
+        # 3. Drizzle schema
+        for drizzle_file in project_dir.rglob("schema.ts"):
+            if "node_modules" not in drizzle_file.parts:
+                text = drizzle_file.read_text(encoding="utf-8", errors="ignore")
+                found = re.findall(r"export\s+const\s+([A-Za-z0-9_]+)\s+=\s+(?:pgTable|mysqlTable|sqliteTable)", text)
+                for m in found:
+                    models.append(f"[Drizzle] {m} ({drizzle_file.relative_to(project_dir).as_posix()})")
+    except Exception:
+        pass
+    return models[:30]
+# ── Satellites Generator (.agents/context/) ───────────────────────────────────
+def generate_satellites(project_dir: Path, force: bool = False) -> dict[str, Path]:
+    """
+    Generate stack-adaptive satellite files in .agents/context/ on-demand.
+    Enforces strict idempotency and zero token bloat in the main hub.
+    """
+    satellites_dir = project_dir / ".agents" / "context"
+    satellites_dir.mkdir(parents=True, exist_ok=True)
+    generated: dict[str, Path] = {}
+    routes = discover_routes(project_dir)
+    models = discover_database_models(project_dir)
+    # 1. routes.md (if web routes detected)
+    if routes:
+        routes_path = satellites_dir / "routes.md"
+        routes_content = (
+            "# System Route & Endpoint Map\n\n"
+            "> Discovered automatically via convention scanner. Used by AI agents for precision navigation.\n\n"
+            "| Kind | Route Path | Implementation File |\n"
+            "| :--- | :--- | :--- |\n"
+        )
+        for r in routes:
+            parts = r.split(" -> ")
+            kind_path = parts[0]
+            impl = parts[1] if len(parts) > 1 else ""
+            routes_content += f"| {kind_path} | `{impl}` |\n"
+        write_idempotent(routes_path, routes_content, "Routes Satellite")
+        generated["routes"] = routes_path
+    # 2. schema.md (if database models detected)
+    if models:
+        schema_path = satellites_dir / "schema.md"
+        schema_content = (
+            "# Database Schema & Entity Models\n\n"
+            "> Discovered data models and ORM schema definitions. Used by AI agents for database context.\n\n"
+            "| Model / Entity | Definition File |\n"
+            "| :--- | :--- |\n"
+        )
+        for m in models:
+            schema_content += f"| {m} |\n"
+        write_idempotent(schema_path, schema_content, "Schema Satellite")
+        generated["schema"] = schema_path
+    # 3. gotchas.md (Critical Traps & Anti-Patterns — Replaces useless bug diaries)
+    gotchas_path = satellites_dir / "gotchas.md"
+    if not gotchas_path.exists() or force:
+        gotchas_content = (
+            "# Critical Gotchas, Anti-Patterns & Architecture Invariants\n\n"
+            "> Institutional knowledge and non-obvious traps that cannot be guessed from reading code.\n\n"
+            "## ⚠️ Active Constraints & Traps\n\n"
+            "1. **Port Invariants:** Inspect discovered ports before binding local services.\n"
+            "2. **Secret Isolation:** Production secrets belong in `.env`; dummy dev accounts belong in `context.local.md`.\n"
+            "3. **State Boundaries:** Verify migrations before initiating build or release cycles.\n"
+        )
+        write_idempotent(gotchas_path, gotchas_content, "Gotchas Satellite")
+        generated["gotchas"] = gotchas_path
+    return generated

auto_context_cli-1.0.3/src/auto_context/templates/context.template.md ADDED Viewed

@@ -0,0 +1,53 @@
+# {{PROJECT_NAME}} — Executive Context Hub
+> **Last Updated:** {{DATE_NOW}} | **Stack:** {{STACK}} ({{FRAMEWORK}})
+> **Directory:** `{{PROJECT_DIR}}` | **Model:** Hub & Satellite (< 400 Tokens)
+---
+<!-- AUTO-CONTEXT:DISCOVERY:START -->
+## 1. Network & Configuration Vault
+> 🔒 **Sandbox Isolation:** Mock dev accounts and local ports live in [`context.local.md`](file://{{PROJECT_DIR}}/context.local.md). Production secrets belong exclusively in `.env`.
+| Service / Key | Port / Setting | Source / Mode |
+| :--- | :--- | :--- |
+| **App Server** | `3000` (Default) | Development |
+| **Test Fixtures** | `context.local.md` | Mock accounts (chmod 600) |
+| **Runtime Secrets** | `.env` | Protected by .gitignore |
+## 2. Stack & Adaptive Satellites
+* **Primary Stack:** {{STACK}} ({{FRAMEWORK}})
+* **Satellites Directory:** [`.agents/context/`](file://{{PROJECT_DIR}}/.agents/context/)
+  - **Critical Gotchas:** [`gotchas.md`](file://{{PROJECT_DIR}}/.agents/context/gotchas.md) — Architecture invariants & traps
+  - **Routes & Endpoints:** [`routes.md`](file://{{PROJECT_DIR}}/.agents/context/routes.md) — Discovered API & page map
+  - **Database Schemas:** [`schema.md`](file://{{PROJECT_DIR}}/.agents/context/schema.md) — Discovered models & ORM entities
+## 3. Operations Runbook
+| Action | Command |
+| :--- | :--- |
+| **Start Development** | `npm run dev` / `python main.py` |
+| **Codebase Rescan** | `init-context scan` |
+<!-- AUTO-CONTEXT:DISCOVERY:END -->
+---
+## 4. Active Invariants & Critical Gotchas
+> ⚠️ Consult [`.agents/context/gotchas.md`](file://{{PROJECT_DIR}}/.agents/context/gotchas.md) before modifying database models, port bindings, or build pipelines.
+1. **Token Conservation:** Do NOT read full component bodies; use Grep / Symbol targeting.
+2. **Secret Safety:** Never commit plaintext credentials or test keys.
+---
+## 5. Skills & Progressive Disclosure Routing
+| Skill | Triggers | Location |
+| :--- | :--- | :--- |
+| **`docker-ops`** | `docker`, `compose` | [SKILL.md](file://{{PROJECT_DIR}}/.agents/skills/docker-ops/SKILL.md) |
+| **`git-workflow`** | `git`, `commit`, `rebase` | [SKILL.md](file://{{PROJECT_DIR}}/.agents/skills/git-workflow/SKILL.md) |
+| **`server-diagnostics`** | `health`, `ram`, `port` | [SKILL.md](file://{{PROJECT_DIR}}/.agents/skills/server-diagnostics/SKILL.md) |
+| **`browser-testing`** | `browser`, `playwright` | [SKILL.md](file://{{PROJECT_DIR}}/.agents/skills/browser-testing/SKILL.md) |

auto_context_cli-1.0.3/src/auto_context/templates/rules/hub-satellite-architecture.md ADDED Viewed

@@ -0,0 +1,33 @@
+---
+name: hub-satellite-architecture
+description: Enforces the Hub & Satellite modular context pattern, strict idempotency, token budget ceilings, and the Brutal Truth Filter across all projects.
+trigger: always_on
+---
+# Rule: Hub & Satellite Modular Architecture & Idempotency Proof
+## Objective
+Prevent monolithic context file bloat, eliminate token waste, ensure 100% idempotent execution, and enforce high-value institutional knowledge retention across all coding tasks.
+## Guidelines & Constraints
+1. **Hub & Satellite Pattern (Strict Token Budget):**
+   - Primary `context.md` serves solely as an **Executive Hub** and MUST NOT exceed **80 lines / ~400 tokens**.
+   - Detailed domain specifics must be separated into stack-adaptive satellite files inside `.agents/context/` (e.g. `routes.md`, `schema.md`, `gotchas.md`).
+   - Satellites are dynamically loaded on-demand via progressive disclosure, preserving conversation context window budgets.
+2. **Strict Idempotency Proof ($f(f(x)) = f(x)$):**
+   - Running context generation or sync commands 1 time or 100 times must produce the exact same deterministic result without duplicating blocks.
+   - Use anchored block delimiters (`<!-- AUTO-CONTEXT:<TAG>:START --> ... <!-- AUTO-CONTEXT:<TAG>:END -->`).
+   - Re-running replaces block contents rather than appending.
+   - User-written notes, secrets, and manual entries outside anchored zones must remain 100% untouched.
+   - Check content hashes before disk writes to avoid unnecessary I/O.
+3. **The Brutal Truth Filter (Zero Dead Logs):**
+   - If an idea, log entry, or feature fails first-principles scrutiny, drop it immediately and inform the user.
+   - Prohibit chronological bug cemeteries (`history.md` dumps of trivial solved bugs).
+   - In their place, maintain **`gotchas.md`**: high-impact institutional knowledge, non-obvious architecture traps, port collisions, and edge-case invariants.
+4. **KISS & DRY Heuristics:**
+   - Prefer language-agnostic filesystem convention heuristics (directories, manifests) over heavy language AST parsers that crash on in-flight syntax errors.
+   - All scanners must degrade gracefully with zero unhandled exceptions.

auto_context_cli-1.0.3/src/auto_context/templates/rules/readme-docs-sync.md ADDED Viewed

@@ -0,0 +1,23 @@
+---
+name: readme-docs-sync
+description: Mandates immediate documentation synchronization in README.md whenever features, commands, or workflows are added or updated in auto-context or any Git repository.
+trigger: always_on
+---
+# Rule: Mandatory README & Documentation Synchronization
+## Objective
+Ensure that all features, subcommands, options, and architectural workflows in `auto-context` or any active Git repository are comprehensively, accurately, and immediately documented in `README.md` with proper executable commands and instructions.
+## Guidelines & Constraints
+1. **Zero Undocumented Features:**
+   - Whenever a new feature, CLI command, option, flag, or architectural capability is added or modified, `README.md` MUST be updated before committing or releasing.
+   - Both the English reference documentation and the Bengali guide (বাংলা নির্দেশিকা) must be updated.
+2. **Clear & Executable Instructions:**
+   - Every command documented must be 100% executable and tested.
+   - Include clear syntax examples (`init-context update`, `init-context promote`, `init-context memory`, etc.), options tables, and expected output.
+3. **Safety & Non-Breaking Boundaries:**
+   - Explicitly document data protection guarantees (e.g. `context.md`, `.env`, and user custom rules are never overwritten or broken).
+4. **Release Version Alignment:**
+   - When bumping package versions (`pyproject.toml`, tags), update release badges and installation commands in `README.md`.

auto_context_cli-1.0.2/src/auto_context/templates/context.template.md DELETED Viewed

@@ -1,94 +0,0 @@
-# {{PROJECT_NAME}} — Master Architectural Context, Problem Log & Operations Manual
-> **Last Updated:** {{DATE_NOW}}
-> **Project Directory:** `{{PROJECT_DIR}}`
-> **Repository Name:** `{{PROJECT_NAME}}`
-> **Primary Stack:** {{STACK}} ({{FRAMEWORK}})
----
-## 1. Master Credentials & Configuration Vault
-> 🔒 **Local Sandbox Isolation:** Mock test logins, seed users, and local dev ports are stored in [`context.local.md`](file://{{PROJECT_DIR}}/context.local.md) (strictly protected by `.gitignore` and `chmod 600`). Real secrets reside exclusively in `.env`.
-| Property | Value / Setting | Description |
-| :--- | :--- | :--- |
-| **Project Name** | `{{PROJECT_NAME}}` | Active project identifier |
-| **Environment** | Development / Production | Current runtime environment |
-| **Base Port** | TBD | Application listening port |
-| **API Endpoints** | TBD | Service URL / Domains |
-| **Secrets / Keys** | Secured in Vault | Credentials, API tokens, passwords |
-| **Test Fixtures** | `context.local.md` | Local dummy test credentials (git-ignored) |
----
-## 2. Chronological Problem Log & Technical Solutions
-```mermaid
-flowchart TD
-    Init["1. Project Initialized"] --> Ready["Ready for development"]
-```
-| # | Symptom / Error Message | Root Cause | Exact CLI Solution & Code Patch |
-| :-: | :--- | :--- | :--- |
-| 1 | Initial setup | Clean repository initialization | Generated autonomous context framework |
----
-## 3. System Architecture & Tech Stack
-* **Primary Stack:** {{STACK}}
-* **Framework:** {{FRAMEWORK}}
-* **Database / Cache:** TBD
-* **Deployment Target:** TBD
-```
-{{PROJECT_NAME}}/
-├── .agents/
-│   ├── rules/
-│   │   ├── code-standards.md
-│   │   ├── maintain_context.md
-│   │   └── security-boundaries.md
-│   └── skills/
-│       ├── browser-testing/
-│       ├── docker-ops/
-│       ├── git-workflow/
-│       └── server-diagnostics/
-├── AGENTS.md
-├── GEMINI.md
-├── context.local.md
-└── context.md
-```
----
-## 4. Setup, Reproduction & Operations Runbook
-### Prerequisites
-* Operating System: Linux / WSL2 / Windows / macOS
-* Runtime / Package Manager: TBD
-### Quick Start
-```bash
-# Setup instructions will be populated automatically by AI assistant
-```
----
-## 5. Skills & Progressive Disclosure Catalog
-> 💡 **Progressive Disclosure Protocol:** Agents must NOT read full `SKILL.md` files upfront. When user prompts match any triggers, dynamically inspect the skill file using `read_file`.
-| Skill | Version | Purpose & Scope | Triggers | Location |
-| :--- | :---: | :--- | :--- | :--- |
-| **`docker-ops`** | 1.0.0 | Production Dockerfile & Compose orchestration | `docker`, `container`, `compose` | [SKILL.md](file://{{PROJECT_DIR}}/.agents/skills/docker-ops/SKILL.md) |
-| **`git-workflow`** | 1.0.0 | Conventional commits & merge conflict resolution | `git`, `commit`, `branch`, `rebase` | [SKILL.md](file://{{PROJECT_DIR}}/.agents/skills/git-workflow/SKILL.md) |
-| **`server-diagnostics`** | 1.0.0 | System health, RAM/swap, CPU, ports & sockets | `health`, `ram`, `cpu`, `swap`, `port` | [SKILL.md](file://{{PROJECT_DIR}}/.agents/skills/server-diagnostics/SKILL.md) |
-| **`browser-testing`** | 1.0.0 | UI testing & mock logins using `context.local.md` | `browser`, `playwright`, `puppeteer`, `ui-test` | [SKILL.md](file://{{PROJECT_DIR}}/.agents/skills/browser-testing/SKILL.md) |
----
-## 6. Autonomous Documentation Policy
-* Maintained automatically by AI assistants (Antigravity, Cursor, Claude Code, Copilot, Cline, Windsurf) on every code or configuration change.
-* Governed by [`GEMINI.md`](file://{{PROJECT_DIR}}/GEMINI.md) and [`.agents/rules/maintain_context.md`](file://{{PROJECT_DIR}}/.agents/rules/maintain_context.md).