@azerogluemin/ai-bootstrap 0.2.1 → 0.4.1

package/CHANGELOG.md

@@ -5,6 +5,167 @@ All notable changes to `@azerogluemin/ai-bootstrap` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1] — 2026-06-21
+
+README rewrite — published so npm.com lands on the new usage guide.
+
+### Changed
+
+- packages/cli/README.md — full rewrite (AZ):
+  - 2-step TL;DR quick start
+  - User scope vs. project scope explained with table
+  - 5 real workflow scenarios (Creator/IG, SaaS, SMM, add bundle, remove)
+  - All commands grouped by purpose (setup, mgmt, MCP, backup, telemetry)
+  - 63 MCP server categorized list
+  - Troubleshooting section (5 common issues)
+- No functional code changes vs. 0.4.0.
+
+[0.4.1]: https://github.com/eminazeroglu/ai-bootstrap/releases/tag/v0.4.1
+
+## [0.4.0] — 2026-06-21
+
+Incremental skill + agent management — add / remove / list.
+
+### Added
+
+- **`ai-bootstrap add <names>`** — install additional skills or agents
+  - Auto-detects skill vs agent by template lookup
+  - `--bundle <name>` merges an entire bundle
+  - Auto-detects scope (project if CLAUDE.md / .claude/ in cwd, else user)
+  - `--user` / `--project` flags force scope
+- **`ai-bootstrap remove <names>` (alias: `rm`)** — uninstall skills/agents
+  - Same scope auto-detection
+  - Removes from both skills/ and agents/ if name matches both
+- **`ai-bootstrap list` (alias: `ls`)** — list installed skills/agents
+  - Current scope by default
+  - `--user`, `--project`, or `--all` flags
+  - `--all` shows user scope + current project side-by-side
+
+### Why
+
+v0.3.0 introduced `new` for project bootstrap with a single bundle. But real
+users hit edge cases:
+- Picked `developer` bundle, later need `showrunner` for a marketing page
+- Picked `creator`, later need `seo-technical` for SEO audit
+- Want to remove unused skills to reduce context noise
+
+`add` / `remove` / `list` give granular control without re-running the whole wizard.
+
+### Workflow examples
+
+```bash
+# Already have a developer-bundle project, need creator skills too:
+ai-bootstrap add showrunner character-designer image-prompt-engineer
+
+# Or merge whole creator bundle on top:
+ai-bootstrap add --bundle creator
+
+# See what's installed in this project:
+ai-bootstrap list
+
+# See user + project side by side:
+ai-bootstrap list --all
+
+# Drop a skill you don't use:
+ai-bootstrap remove security-auditor
+```
+
+### Tests
+
+- New e2e tests: add help, list empty user scope, remove non-existent graceful
+- 134 passing (was 131): 87 smoke + 47 e2e
+
+[0.4.0]: https://github.com/eminazeroglu/ai-bootstrap/releases/tag/v0.4.0
+
+## [0.3.0] — 2026-06-21
+
+Project-scope skills + agents — different bundles per project.
+
+### Added
+
+- **`ai-bootstrap new` subcommand** — bootstrap any folder as a project:
+  1. Ask the project name (defaults to folder name)
+  2. Ask "what is this project?" with 9 intent choices that auto-map to a bundle:
+     - SaaS / Fullstack → developer
+     - AI Creator content → creator
+     - Marketing / SMM → marketer
+     - Mobile app → developer
+     - Data analysis / dashboard → developer
+     - Client agency work → full-stack
+     - Startup / founder → founder
+     - Open source library → developer
+     - Just basics → foundation
+  3. Allow bundle override
+  4. Ask for 1-2 sentence project description (goes into CLAUDE.md)
+  5. Allow custom project-specific rules
+  6. Install skills to `<project>/.claude/skills/` (PROJECT scope)
+  7. Install agents to `<project>/.claude/agents/` (PROJECT scope)
+  8. Write `<project>/CLAUDE.md` with project metadata + bundle reference
+  9. Save state to `<project>/.claude/ai-bootstrap-project.json`
+
+### Why this matters
+
+Previously, ai-bootstrap installed ONE bundle globally (`~/.claude/`). Every
+project saw the same skill set. Real users have multiple identities — AI
+creator on Monday, full-stack dev on Tuesday, marketer on Wednesday — and
+need different skills per project.
+
+Claude Code's project-scope skills (`<project>/.claude/skills/`) load ONLY
+when working inside that project. This gives you the right tools per context
+without polluting every session.
+
+### Changed
+
+- `installSkills(names, targetDir?)` — second arg defaults to `~/.claude/skills/`
+  for backward compat; project install passes `<project>/.claude/skills/`
+- `installAgents(names, targetDir?)` — same pattern
+- Help text reorganized: user-scope wizard vs project-scope `new`
+
+### Testing
+
+- New smoke test: 'project-scope install' — verifies skills install to
+  project dir, user-scope dir NOT affected
+- E2E test updated for help text changes
+- 127 tests passing (was 124)
+
+### Workflow
+
+```bash
+# Once per machine — universal foundation:
+npx @azerogluemin/ai-bootstrap   # picks foundation/minimal user-scope
+
+# Then per project:
+cd ~/Projects/my-saas && ai-bootstrap new     # → developer bundle
+cd ~/Projects/azerogluemin-content && ai-bootstrap new   # → creator bundle
+cd ~/Clients/restaurant-smm && ai-bootstrap new   # → marketer bundle
+```
+
+Each project sees only its own bundle. No skill pollution.
+
+[0.3.0]: https://github.com/eminazeroglu/ai-bootstrap/releases/tag/v0.3.0
+
+## [0.2.2] — 2026-06-21
+
+User-autonomy fixes from first real-world test feedback.
+
+### Fixed
+
+- **Wizard step 6 (GitHub backup) over-validated URLs**:
+  - Now accepts both SSH (`git@github.com:user/repo`) and HTTPS
+  - Empty input is now allowed → defer URL to `ai-bootstrap backup init` later
+  - User no longer locked into giving a URL at wizard time
+- **`backup init` refused public repos outright**:
+  - Now warns + asks for explicit confirmation instead of hard-blocking
+  - Rationale: user autonomy — the user knows their threat model
+
+### Why
+
+In v0.2.1 test, the wizard rejected a valid SSH URL and refused to proceed.
+Two design errors: (1) regex was https-only, (2) URL was mandatory if user
+said "yes" to backup. Both fixed.
+
+[0.2.2]: https://github.com/eminazeroglu/ai-bootstrap/releases/tag/v0.2.2
+
 ## [0.2.1] — 2026-06-21
 
 First published version on npm.

package/README.md

@@ -1,139 +1,347 @@
 # @azerogluemin/ai-bootstrap
 
-> Personal AI infrastructure bootstrap for Claude Code — one command sets up skills, agents, MCPs, and cross-project memory.
+> **Bir komanda. Hər layihə. Hər maşın. Claude Code hər şeyi yadda saxlayır.**
 
+[![npm](https://img.shields.io/npm/v/@azerogluemin/ai-bootstrap.svg?logo=npm&label=npm)](https://www.npmjs.com/package/@azerogluemin/ai-bootstrap)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
 [![Node ≥22](https://img.shields.io/badge/Node-%E2%89%A522-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
-[![GitHub](https://img.shields.io/badge/GitHub-eminazeroglu%2Fai--bootstrap-181717?logo=github)](https://github.com/eminazeroglu/ai-bootstrap)
 
-## Quick start
+## TL;DR — 2 addım
 
 ```bash
+# 1) Bir dəfə bütün maşına (foundation: 10 universal skill)
 npx @azerogluemin/ai-bootstrap
+
+# 2) Hər yeni layihədə (bundle: layihənin növünə uyğun skill-lər)
+cd ~/Projects/yeni-layihə
+ai-bootstrap new
 ```
 
-Interactive 6-step setup:
+Bitdi. Hər layihədə sadəcə `claude` yaz — uyğun skill + agent dəstləri özü yüklənir.
+
+---
+
+## Necə işləyir — 2 səviyyəli skill sistemi
 
-1. **Profile** — name, role, languages, experience, 6/12/24-month goals
-2. **Projects** — scan your folders, catalog projects with CLAUDE.md detection
-3. **Bundles** — pick skill + agent bundle:
-   - `foundation` — 10 essential skills, 2 agents (smallest)
-   - `developer` — 21 skills, 18 agents (engineering focus)
-   - `marketer` — 24 skills, 29 agents (SEO + social + growth)
-   - `creator` — 26 skills, 13 agents (video, music, storyboard)
-   - `founder` — 35 skills, 38 agents (C-Level + business + product)
-   - `full-stack` — 52+ skills, 75+ agents (everything)
-4. **MCPs** — pick from 63 Model Context Protocol servers (github, postgres, supabase, notion, slack, atlassian, gmail, twilio, sendgrid, spotify, kubernetes, …)
-5. **Memory** — markdown + git knowledge architecture (25-50× faster than vector DB at <100K entries)
-6. **GitHub** — optional `~/.claude/` backup repo
+Claude Code skill-ləri **2 səviyyəlidir**:
 
-Result: a Claude Code workstation that remembers everything across projects, machines, and sessions.
+| Səviyyə | Yer | Nə vaxt yüklənir |
+|---|---|---|
+| **User scope** (qlobal) | `~/.claude/skills/` | Hər layihədə, hər session-da |
+| **Project scope** (lokal) | `<layihə>/.claude/skills/` | YALNIZ o qovluqda |
 
-## What you get
+ai-bootstrap bunun ikisini də idarə edir:
+- **`npx @azerogluemin/ai-bootstrap`** → user scope (foundation: 10 əsas skill, universal lazımdır)
+- **`ai-bootstrap new`** → project scope (layihə növünə uyğun bundle)
 
-- **85+ production skills** spanning Foundation, Product, Marketing, Social, Creator, Graphic Design, Coaching, Productivity, Engineering, C-Level Advisory, Verticals
-- **75+ specialized agents** including SEO suite (18), C-Level mirrors (10), Engineering (14), Social orchestrators (5), Marketing (6), Vertical specialists (8), Product team (5)
-- **63 MCP servers** in catalog with real install commands + OAuth/credential helpers (stdio + HTTP transports)
-- **Universal CLAUDE.md** with 8 foundation rules (docs-first, learning-keeper auto-promotion, dürüst dialoq, etc.)
-- **Knowledge skeleton**: `user-profile`, `mistakes-log`, `verified-facts`, `user-rules`, `patterns`, `handoff-log`, language guides, projects manifest
-- **Interactive permission gates** via Claude Code's settings.json
+Beləliklə **AI Creator** layihən və **SaaS** layihən fərqli skill dəstləri görür. Token israfı yoxdur.
 
-## Commands
+---
+
+## İlk dəfə qurulum (bir dəfə maşına)
 
 ```bash
-# Default
-ai-bootstrap                  # Interactive 6-step wizard
+npx @azerogluemin/ai-bootstrap
+```
 
-# Sync + diagnose
-ai-bootstrap update           # Re-sync skills + agents from latest bundle
-ai-bootstrap doctor           # Diagnose install health (symlinks, MCPs, creds)
+Wizard 6 addım soruşur:
 
-# MCP management
-ai-bootstrap mcp list         # List all 63 MCP servers available
-ai-bootstrap mcp installed    # List MCPs configured on this machine
-ai-bootstrap mcp credentials  # Interactively fill MCP credentials
+1. **Profile** — adın, rolun, dillərin, 6/12/24 ay məqsədlərin
+2. **Projects** — mövcud layihələri scan etmək istəyirsən? (boş burax — sonra qurarsan)
+3. **Bundle** — **`foundation`** seç (qlobal yalnız əsas 10 skill lazımdır; qalanlar project scope-da)
+4. **MCPs** — istədiyin MCP server-ləri seç (məs. github, instagram, brave-search)
+5. **Memory** — `markdown-only` (default tövsiyə)
+6. **GitHub backup** — istərsən qur, istəməsən boş burax (sonra `ai-bootstrap backup init`)
 
-# Git backup of ~/.claude/
-ai-bootstrap backup init      # Initialize: git init + remote + first push
-ai-bootstrap backup sync      # Stage + commit + push current state
-ai-bootstrap backup pull      # Restore on a new machine
-ai-bootstrap backup status    # Show remote + last sync
+Yoxla:
+```bash
+ai-bootstrap doctor
+```
+Hər şey ✓ olmalıdır.
 
-# Telemetry (opt-in, default OFF)
-ai-bootstrap telemetry status # Show current setting
-ai-bootstrap telemetry on     # Opt in (anonymous: version, bundles, MCP IDs)
-ai-bootstrap telemetry off    # Opt out
+MCP credential əlavə et (məs. github, instagram tokenları):
+```bash
+ai-bootstrap mcp credentials
+```
 
-# Meta
-ai-bootstrap --version
-ai-bootstrap --help
+`~/.zshrc`-ə (yaxud `~/.bashrc`) bir dəfə əlavə et:
+```bash
+echo 'set -a; [ -f ~/.ai-bootstrap.env ] && source ~/.ai-bootstrap.env; set +a' >> ~/.zshrc
+source ~/.zshrc
 ```
 
-## Architecture (3-layer memory)
+---
+
+## Hər yeni layihədə (1 komanda)
 
+```bash
+cd ~/Projects/yeni-layihə
+ai-bootstrap new
 ```
-Layer 1: ~/.claude/CLAUDE.md       — universal rules loaded every session
-Layer 2: ~/.claude/knowledge/      — cross-project markdown memory
-Layer 3: learning-keeper skill     — auto-captures corrections + promotes
-                                     project knowledge → universal when applicable
+
+Wizard soruşur: **"Bu qovluqda nə etmək istəyirsən?"**
+
+| Sənin cavab | Bundle | Skill | Agent |
+|---|---|---|---|
+| SaaS / Fullstack web app | `developer` | 21 | 18 |
+| AI Creator content | `creator` | 26 | 13 |
+| Marketing / SMM | `marketer` | 24 | 29 |
+| Mobile app | `developer` | 21 | 18 |
+| Data analysis / dashboard | `developer` | 21 | 18 |
+| Client agency work | `full-stack` | 52+ | 75+ |
+| Startup / founder | `founder` | 35 | 38 |
+| Open source library | `developer` | 21 | 18 |
+| Just basics | `foundation` | 10 | 2 |
+
+Yazır:
+- `<layihə>/.claude/skills/` — layihəyə xas skill-lər
+- `<layihə>/.claude/agents/` — layihəyə xas agent-lər
+- `<layihə>/CLAUDE.md` — layihə qaydaları + təsvir
+
+İndi:
+```bash
+claude
 ```
+Yalnız bu layihənin skill dəsti yüklənir.
 
-## Files written
+---
 
-| Path | Purpose |
-|---|---|
-| `~/.claude/CLAUDE.md` | Universal foundation rules |
-| `~/.claude/settings.json` | Permissions, model preference, hooks |
-| `~/.claude/knowledge/*.md` | Cross-project knowledge |
-| `~/.claude/skills/<name>/` | Installed skill (copied from template) |
-| `~/.claude/agents/<name>/` | Installed agent (copied from template) |
-| `~/.claude.json` | MCP server configs (Claude Code reads this) |
-| `~/.claude/mcp-tracking.json` | ai-bootstrap metadata: which MCPs, what creds needed |
-| `~/.claude/ai-bootstrap-state.json` | Saved bundle selection (for `update`) |
-| `~/.ai-bootstrap.env` | MCP credentials (chmod 600, source in shell) |
+## Real istifadə nümunələri
 
-## MCP credentials
+### Senaryo 1: AI Creator layihəsi (məs. Instagram brand)
 
-After setup, fill credentials:
+```bash
+mkdir -p ~/Projects/azerogluemin-content && cd ~/Projects/azerogluemin-content
+ai-bootstrap new
+# Soruşur → "AI Creator content" seç → creator bundle
+# 26 skill: showrunner, character-designer, image-prompt-engineer,
+#          video-prompt-engineer, youtube-thumbnail-designer,
+#          brand-identity-designer, instagram-expert, ...
+# 13 agent: video-pipeline, storyboard-orchestrator, sound-designer, ...
+
+claude
+> "10 günlük IG content calendar yarat — AZ-də, mövzu AI-creator workflow"
+> "Reel hook yaz: developer → AI creator pivot"
+> "YouTube thumbnail dizayn et: AI bootstrap launch"
+```
+
+### Senaryo 2: SaaS layihə
 
 ```bash
-ai-bootstrap mcp credentials
+mkdir -p ~/Projects/restoran-crm && cd ~/Projects/restoran-crm
+ai-bootstrap new
+# → "SaaS / Fullstack web app" → developer bundle
+# 21 skill: architect, backend, frontend, devops, security-auditor, ...
+# 18 agent: code-reviewer, backend-engineer, frontend-engineer, db-migrator, ...
+
+claude
+> "Multi-tenant restoran CRM arxitekturası dizayn et"
+> "Postgres RLS policy yaz hər tenant üçün"
 ```
 
-This writes `~/.ai-bootstrap.env` (chmod 600). Source in your shell so Claude Code picks up `${VAR}` substitutions in `~/.claude.json`:
+### Senaryo 3: Müştəri SMM işi
 
 ```bash
-# In ~/.zshrc or ~/.bashrc:
-set -a; source ~/.ai-bootstrap.env; set +a
+mkdir -p ~/Clients/restoran-smm && cd ~/Clients/restoran-smm
+ai-bootstrap new
+# → "Marketing / SMM" → marketer bundle
+# 24 skill: seo-optimizer, copywriter-pro, social-strategist,
+#          paid-ads-strategist, content-strategist, ...
+# 29 agent: 18 SEO agent + social orchestrators + marketing agents
+
+claude
+> "Restoran üçün 30 günlük IG content plan + Reel hook-lar"
+> "SEO audit et müştərinin saytında"
 ```
 
-## Requirements
+### Senaryo 4: Bundle əskik gəlir, əlavə skill lazımdır
 
-- **Node.js ≥ 22** — uses native ESM, fs/promises, modern path helpers
-- **macOS / Linux / WSL2** — primary targets (Windows native is best-effort)
-- **Disk** — ~3 MB for templates + your generated `~/.claude/` content
+```bash
+cd ~/Projects/restoran-crm   # developer bundle qurulub
+# İndi müştəri marketing landing page istəyir, creator skill-ləri lazımdır:
+ai-bootstrap add showrunner image-prompt-engineer brand-identity-designer
+
+# Yaxud bütün creator bundle əlavə et:
+ai-bootstrap add --bundle creator
+```
+
+### Senaryo 5: İstifadə etmədiyini sil
+
+```bash
+ai-bootstrap list                # bu layihənin skill-ləri
+ai-bootstrap list --all          # user + bu layihə yan-yana
+ai-bootstrap remove security-auditor   # silmək
+```
+
+---
+
+## Bütün komandalar
+
+### Setup + sync
+```bash
+npx @azerogluemin/ai-bootstrap    # ilk qurulum (user scope, bir dəfə)
+ai-bootstrap new                    # bu qovluğa layihə bundle (hər layihədə)
+ai-bootstrap update                 # yeni versiyada skill-ləri yenilə
+ai-bootstrap doctor                 # sağlamlıq yoxlaması
+```
+
+### Skill management
+```bash
+ai-bootstrap add <name1> <name2>            # konkret skill/agent əlavə
+ai-bootstrap add --bundle <name>            # bütün bundle əlavə
+ai-bootstrap remove <name>                  # sil (alias: rm)
+ai-bootstrap list                           # bu scope-da quraşdırılanlar
+ai-bootstrap list --all                     # user + project hamısı (alias: ls)
+ai-bootstrap list --user                    # yalnız user scope
+ai-bootstrap list --project                 # yalnız bu layihə
+```
 
-## Development
+### MCP servers (Instagram, GitHub, Supabase və s.)
+```bash
+ai-bootstrap mcp list               # 63 mövcud MCP göstər
+ai-bootstrap mcp installed          # quraşdırılan MCP-lər
+ai-bootstrap mcp credentials        # token-ləri əlavə et
+```
+
+### Backup (xeyrli)
+```bash
+ai-bootstrap backup init            # private GitHub repo-ya bağla
+ai-bootstrap backup sync            # dəyişikliyi push et
+ai-bootstrap backup pull            # yeni maşında bərpa
+ai-bootstrap backup status          # son sinx + remote
+```
+
+### Telemetry (default OFF, opt-in)
+```bash
+ai-bootstrap telemetry on/off/status
+```
+
+---
+
+## Bundle siyahısı
+
+| Bundle | Skill | Agent | Nə üçün |
+|---|---|---|---|
+| `foundation` | 10 | 2 | Universal əsas — user scope-a tövsiyə |
+| `developer` | 21 | 18 | SaaS, fullstack, mobile, data, open source |
+| `creator` | 26 | 13 | Video, Reel, sosial content, brand |
+| `marketer` | 24 | 29 | SEO, SMM, copywriting, ads (18 SEO agent) |
+| `founder` | 35 | 38 | C-Level advisory + product + marketing |
+| `full-stack` | 52+ | 75+ | Hamısı — multi-rol agency işi |
+
+Tam siyahı: `npx @azerogluemin/ai-bootstrap mcp list` (MCP-lər) yaxud GitHub repo-da [packages/templates/](https://github.com/eminazeroglu/ai-bootstrap/tree/main/packages/templates).
+
+---
+
+## 63 MCP server (real install komanda-ları ilə)
+
+**Dev**: github, gitlab, filesystem, git, fetch, puppeteer, playwright, vercel, cloudflare, aws, netlify, brave-search, firecrawl, tavily, exa, kubernetes, browserbase, apify, time
+
+**Data**: postgres, supabase, mongodb, sqlite, redis, airtable
+
+**Productivity**: notion, linear, obsidian, slack, discord, memory, atlassian (Jira + Confluence), trello, asana, clickup
+
+**Social**: instagram, twitter, meta, youtube, linkedin, tiktok, telegram
+
+**AI**: openai, anthropic, elevenlabs, replicate, perplexity
+
+**Creator**: figma, spotify, youtube-transcript
+
+**Business**: stripe, hubspot, salesforce, twilio, sendgrid
+
+**Analytics**: ga4, sentry, posthog
+
+**Research**: arxiv
+
+**Google Workspace** (HTTP/OAuth): gmail, google-drive, google-calendar, google-chat
+
+---
+
+## 3 səviyyəli yaddaş
+
+```
+~/.claude/CLAUDE.md           ← universal qaydalar (hər session)
+~/.claude/knowledge/          ← cross-layihə yaddaş (markdown + git)
+learning-keeper skill         ← səhvləri yadda saxlayır, qaydaya çevirir
+```
+
+learning-keeper skill xüsusi: söhbətdə düzəliş edirsənsə ("yox elə yox, belə"), bu skill o düzəlişi `~/.claude/knowledge/mistakes-log.md`-ə yazır. Növbəti dəfə həmin səhvi etməyəcək.
+
+---
+
+## Files written
+
+| Yer | Nə üçün |
+|---|---|
+| `~/.claude/CLAUDE.md` | Universal foundation qaydalar |
+| `~/.claude/settings.json` | Permission, model, hook |
+| `~/.claude/knowledge/*.md` | Cross-layihə yaddaş |
+| `~/.claude/skills/<name>/` | User-scope skill (qlobal) |
+| `~/.claude/agents/<name>/` | User-scope agent (qlobal) |
+| `~/.claude.json` | MCP server konfiqurasiyaları |
+| `~/.claude/mcp-tracking.json` | ai-bootstrap metadata |
+| `~/.ai-bootstrap.env` | MCP credential-lar (chmod 600) |
+| `<layihə>/CLAUDE.md` | Layihə qaydaları |
+| `<layihə>/.claude/skills/` | Project-scope skill (yalnız bu qovluqda) |
+| `<layihə>/.claude/agents/` | Project-scope agent |
+| `<layihə>/.claude/ai-bootstrap-project.json` | Layihə bundle state |
+
+---
+
+## Tələblər
+
+- **Node.js ≥ 22**
+- **macOS / Linux / WSL2** — primary; Windows native best-effort
+- **Disk**: ~3 MB templates + sənin yaratdığın yaddaş
+
+---
+
+## Problem həlli
+
+### `ai-bootstrap: command not found`
+`npx @azerogluemin/ai-bootstrap` ilə qaçırılırsa global yox. Düzəliş: ya `npm i -g @azerogluemin/ai-bootstrap`, yaxud həmişə `npx @azerogluemin/ai-bootstrap@latest <command>`.
+
+### `npm publish` 404
+Scope səhvdir. Paket adı `@<sənin npm username>/...` ilə başlamalıdır.
+
+### `ai-bootstrap doctor` failure göstərir
+- Symlink qırılıbsa → `ai-bootstrap update` qaçır
+- MCP creds yoxdursa → `ai-bootstrap mcp credentials`
+- CLAUDE.md yoxdursa → `npx @azerogluemin/ai-bootstrap` yenidən qaçır
+
+### Skill aktivləşmir Claude-da
+- Doğru qovluqda olduğunu yoxla (`pwd`)
+- Project scope qurulubsa → `<layihə>/.claude/skills/` mövcuddur?
+- `ai-bootstrap list` ilə təsdiq et
+
+### MCP server connect olmur
+- `~/.ai-bootstrap.env`-də credential-lar var?
+- Shell yenidən load et: `source ~/.zshrc`
+- `ai-bootstrap doctor` yoxla
+
+---
+
+## Development (contribute etmək üçün)
 
 ```bash
 git clone https://github.com/eminazeroglu/ai-bootstrap.git
 cd ai-bootstrap
 
-pnpm install                   # install monorepo deps
+pnpm install
 pnpm --filter @azerogluemin/ai-bootstrap build
-pnpm --filter @azerogluemin/ai-bootstrap test    # runs 124 tests (81 smoke + 43 e2e)
-
-# Run locally without npx
-node packages/cli/bin/init.js
+pnpm --filter @azerogluemin/ai-bootstrap test    # 134+ test (smoke + e2e)
 
-# Test in isolated HOME (no risk to your real ~/.claude/)
+# Lokal test isolated HOME-da:
 HOME=/tmp/ab-sandbox node packages/cli/bin/init.js
 ```
 
+Detallı [CONTRIBUTING.md](https://github.com/eminazeroglu/ai-bootstrap/blob/main/CONTRIBUTING.md).
+
+---
+
 ## License
 
-MIT — fork, modify, distribute freely.
+[MIT](./LICENSE) — fork, modify, distribute.
 
 ## Author
 
@@ -143,4 +351,5 @@ Built by [Emin Azəroğlu](https://github.com/eminazeroglu) ([@azerogluemin_ai](
 
 - [GitHub repo](https://github.com/eminazeroglu/ai-bootstrap)
 - [Issues](https://github.com/eminazeroglu/ai-bootstrap/issues)
-- [npm](https://www.npmjs.com/package/@azerogluemin/ai-bootstrap)
+- [Changelog](./CHANGELOG.md)
+- [Security policy](https://github.com/eminazeroglu/ai-bootstrap/blob/main/SECURITY.md)

package/dist/applier/agents-installer.d.ts

@@ -9,4 +9,10 @@ export interface AgentInstallResult {
         error: string;
     }[];
 }
-export declare function installAgents(agentNames: string[]): AgentInstallResult;
+/**
+ * Install agents into a target agents directory.
+ * @param agentNames List of agent IDs to install
+ * @param targetAgentsDir Absolute path. Default `~/.claude/agents/`; pass
+ *                       `<project>/.claude/agents/` for project-scope.
+ */
+export declare function installAgents(agentNames: string[], targetAgentsDir?: string): AgentInstallResult;

package/dist/applier/agents-installer.js

@@ -21,13 +21,19 @@ function templatesAgentsPath() {
     }
     return candidates[0];
 }
-export function installAgents(agentNames) {
+/**
+ * Install agents into a target agents directory.
+ * @param agentNames List of agent IDs to install
+ * @param targetAgentsDir Absolute path. Default `~/.claude/agents/`; pass
+ *                       `<project>/.claude/agents/` for project-scope.
+ */
+export function installAgents(agentNames, targetAgentsDir = AGENTS_DIR) {
     const result = {
         installed: [],
         skipped: [],
         errors: [],
     };
-    ensureDir(AGENTS_DIR);
+    ensureDir(targetAgentsDir);
     const templatesDir = templatesAgentsPath();
     if (!existsSync(templatesDir)) {
         for (const name of agentNames) {
@@ -40,7 +46,7 @@ export function installAgents(agentNames) {
     }
     for (const name of agentNames) {
         const sourceDir = join(templatesDir, name);
-        const targetDir = join(AGENTS_DIR, name);
+        const targetDir = join(targetAgentsDir, name);
         if (!existsSync(sourceDir)) {
             result.skipped.push({
                 agent: name,

package/dist/applier/agents-installer.js.map

@@ -1 +1 @@
-{"version":3,"file":"agents-installer.js","sourceRoot":"","sources":["../../src/applier/agents-installer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agents-installer.js","sourceRoot":"","sources":["../../src/applier/agents-installer.ts"],"names":[],"mappings":"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"}

package/dist/applier/skills-installer.d.ts

@@ -9,4 +9,10 @@ export interface SkillInstallResult {
         error: string;
     }[];
 }
-export declare function installSkills(skillNames: string[]): SkillInstallResult;
+/**
+ * Install skills into a target skills directory.
+ * @param skillNames List of skill IDs to install
+ * @param targetSkillsDir Absolute path to the skills directory (default: `~/.claude/skills/`).
+ *                       Pass `<project>/.claude/skills/` for project-scope installation.
+ */
+export declare function installSkills(skillNames: string[], targetSkillsDir?: string): SkillInstallResult;