docs: improve documentation coherence across codebase

webdocs/api-reference/claude-code-v1-api.mdx

@@ -5,7 +5,7 @@ description: "FastSkill implementation of Claude Code v1 API specification for s
 
 ## Overview
 
-FastSkill implements the Claude Code v1 API specification, providing a standardized interface for skill management compatible with Claude Code clients. The v1 API endpoints are prefixed with `/api/code/v1/` and provide CRUD operations for skills and skill versions.
+FastSkill implements the Claude Code v1 API specification, providing a standardized interface for skill management compatible with Claude Code clients. The v1 API endpoints are prefixed with `/v1/` and provide CRUD operations for skills and skill versions.
 
 <Info>
 The Claude Code v1 API is designed for Claude Code clients and provides a standardized skill management interface.
@@ -16,7 +16,7 @@ The Claude Code v1 API is designed for Claude Code clients and provides a standa
 All Claude Code v1 API endpoints use the base path:
 
 ```
-http://localhost:8080/api/code/v1
+http://localhost:8080/v1
 ```
 
 ## Authentication
@@ -30,7 +30,7 @@ curl -X POST http://localhost:8080/auth/token \
   -d '{"role": "manager"}'
 
 # Use token in requests
-curl -X GET http://localhost:8080/api/code/v1/skills \
+curl -X GET http://localhost:8080/v1/skills \
   -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
 ```
 
@@ -44,7 +44,7 @@ The token must have at least `user` role. For creating/updating skills, use `man
 
 List all skills available in the system.
 
-**Endpoint**: `GET /api/code/v1/skills`
+**Endpoint**: `GET /v1/skills`
 
 **Authentication**: Required (user, manager, or admin)
 
@@ -59,11 +59,11 @@ List all skills available in the system.
 **Example**:
 ```bash
 # List all skills
-curl -X GET http://localhost:8080/api/code/v1/skills \
+curl -X GET http://localhost:8080/v1/skills \
   -H "Authorization: Bearer <token>"
 
 # List enabled skills with pagination
-curl -X GET "http://localhost:8080/api/code/v1/skills?enabled=true&limit=10&offset=0" \
+curl -X GET "http://localhost:8080/v1/skills?enabled=true&limit=10&offset=0" \
   -H "Authorization: Bearer <token>"
 ```
 
@@ -95,7 +95,7 @@ curl -X GET "http://localhost:8080/api/code/v1/skills?enabled=true&limit=10&offs
 
 Retrieve details of a specific skill.
 
-**Endpoint**: `GET /api/code/v1/skills/:skill_id`
+**Endpoint**: `GET /v1/skills/:skill_id`
 
 **Authentication**: Required (user, manager, or admin)
 
@@ -108,7 +108,7 @@ Retrieve details of a specific skill.
 **Example**:
 ```bash
 # Get skill details
-curl -X GET http://localhost:8080/api/code/v1/skills/pptx \
+curl -X GET http://localhost:8080/v1/skills/pptx \
   -H "Authorization: Bearer <token>"
 ```
 
@@ -154,7 +154,7 @@ curl -X GET http://localhost:8080/api/code/v1/skills/pptx \
 
 Create a new skill in the system.
 
-**Endpoint**: `POST /api/code/v1/skills`
+**Endpoint**: `POST /v1/skills`
 
 **Authentication**: Required (manager or admin)
 
@@ -195,7 +195,7 @@ Create a new skill in the system.
 
 **Example**:
 ```bash
-curl -X POST http://localhost:8080/api/code/v1/skills \
+curl -X POST http://localhost:8080/v1/skills \
   -H "Authorization: Bearer <token>" \
   -H "Content-Type: application/json" \
   -d '{
@@ -243,53 +243,11 @@ curl -X POST http://localhost:8080/api/code/v1/skills \
 }
 ```
 
-### Update Skill
-
-Update an existing skill.
-
-**Endpoint**: `PUT /api/code/v1/skills/:skill_id`
-
-**Authentication**: Required (manager or admin)
-
-**Path Parameters**:
-
-| Parameter | Type | Required | Description |
-|-----------|--------|-----------|-------------|
-| `skill_id` | string | Yes | Unique skill identifier |
-
-**Request Body**: Same as create skill (all fields optional)
-
-**Example**:
-```bash
-curl -X PUT http://localhost:8080/api/code/v1/skills/web-scraper \
-  -H "Authorization: Bearer <token>" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "description": "Updated description",
-    "version": "1.1.0",
-    "enabled": false
-  }'
-```
-
-**Response** (success):
-```json
-{
-  "success": true,
-  "data": {
-    "id": "web-scraper",
-    "description": "Updated description",
-    "version": "1.1.0",
-    "enabled": false,
-    "updated_at": "2025-02-02T16:00:00Z"
-  }
-}
-```
-
 ### Delete Skill
 
 Delete a skill from the system.
 
-**Endpoint**: `DELETE /api/code/v1/skills/:skill_id`
+**Endpoint**: `DELETE /v1/skills/:skill_id`
 
 **Authentication**: Required (manager or admin)
 
@@ -301,7 +259,7 @@ Delete a skill from the system.
 
 **Example**:
 ```bash
-curl -X DELETE http://localhost:8080/api/code/v1/skills/web-scraper \
+curl -X DELETE http://localhost:8080/v1/skills/web-scraper \
   -H "Authorization: Bearer <token>"
 ```
 
@@ -331,7 +289,7 @@ curl -X DELETE http://localhost:8080/api/code/v1/skills/web-scraper \
 
 Create a new version for an existing skill.
 
-**Endpoint**: `POST /api/code/v1/skills/:skill_id/versions`
+**Endpoint**: `POST /v1/skills/:skill_id/versions`
 
 **Authentication**: Required (manager or admin)
 
@@ -364,7 +322,7 @@ Create a new version for an existing skill.
 
 **Example**:
 ```bash
-curl -X POST http://localhost:8080/api/code/v1/skills/web-scraper/versions \
+curl -X POST http://localhost:8080/v1/skills/web-scraper/versions \
   -H "Authorization: Bearer <token>" \
   -H "Content-Type: application/json" \
   -d '{
@@ -398,7 +356,7 @@ curl -X POST http://localhost:8080/api/code/v1/skills/web-scraper/versions \
 
 List all versions of a skill.
 
-**Endpoint**: `GET /api/code/v1/skills/:skill_id/versions`
+**Endpoint**: `GET /v1/skills/:skill_id/versions`
 
 **Authentication**: Required (user, manager, or admin)
 
@@ -417,7 +375,7 @@ List all versions of a skill.
 
 **Example**:
 ```bash
-curl -X GET http://localhost:8080/api/code/v1/skills/web-scraper/versions \
+curl -X GET http://localhost:8080/v1/skills/web-scraper/versions \
   -H "Authorization: Bearer <token>"
 ```
 
@@ -457,7 +415,7 @@ curl -X GET http://localhost:8080/api/code/v1/skills/web-scraper/versions \
 
 Get details of a specific skill version.
 
-**Endpoint**: `GET /api/code/v1/skills/:skill_id/versions/:version`
+**Endpoint**: `GET /v1/skills/:skill_id/versions/:version`
 
 **Authentication**: Required (user, manager, or admin)
 
@@ -470,7 +428,7 @@ Get details of a specific skill version.
 
 **Example**:
 ```bash
-curl -X GET http://localhost:8080/api/code/v1/skills/web-scraper/versions/1.2.0 \
+curl -X GET http://localhost:8080/v1/skills/web-scraper/versions/1.2.0 \
   -H "Authorization: Bearer <token>"
 ```
 
@@ -495,7 +453,7 @@ curl -X GET http://localhost:8080/api/code/v1/skills/web-scraper/versions/1.2.0
 
 Delete a specific version of a skill.
 
-**Endpoint**: `DELETE /api/code/v1/skills/:skill_id/versions/:version`
+**Endpoint**: `DELETE /v1/skills/:skill_id/versions/:version`
 
 **Authentication**: Required (manager or admin)
 
@@ -508,7 +466,7 @@ Delete a specific version of a skill.
 
 **Example**:
 ```bash
-curl -X DELETE http://localhost:8080/api/code/v1/skills/web-scraper/versions/1.0.0 \
+curl -X DELETE http://localhost:8080/v1/skills/web-scraper/versions/1.0.0 \
   -H "Authorization: Bearer <token>"
 ```
 

webdocs/api-reference/overview.mdx

@@ -122,8 +122,8 @@ curl -X GET http://localhost:8080/
 curl -X POST http://localhost:8080/auth/token \
   -H "Content-Type: application/json" \
   -d '{
-    "username": "user",
-    "password": "pass"
+    "role": "manager",
+    "username": "optional-username"
   }'
 
 # Verify token
@@ -189,7 +189,7 @@ curl -X POST http://localhost:8080/api/registry/publish \
   -F "package=@skill-package.zip"
 
 # Get publish job status
-curl -X GET http://localhost:8080/api/registry/publish/:job_id/status \
+curl -X GET http://localhost:8080/api/registry/publish/status/:job_id \
   -H "Authorization: Bearer <token>"
 ```
 
@@ -291,7 +291,6 @@ use fastskill::SkillFilters;
 
 let filters = SkillFilters {
     enabled: Some(true),
-    tags: Some(vec!["text".to_string(), "nlp".to_string()]),
     ..Default::default()
 };
 
@@ -315,11 +314,11 @@ fastskill serve --host 0.0.0.0 --port 9000
 ### With Registry UI
 
 ```bash
-# Enable registry web UI at /registry
+# Enable registry web UI
 fastskill serve --enable-registry
 ```
 
-Then open `http://localhost:8080/registry` in your browser.
+Then open `http://localhost:8080/` or `http://localhost:8080/dashboard` in your browser.
 
 ## Integration Examples
 
@@ -474,7 +473,7 @@ let results = join_all(tasks).await;
   ```bash
   curl -X POST http://localhost:8080/auth/token \
     -H "Content-Type: application/json" \
-    -d '{"username": "user", "password": "pass"}'
+    -d '{"role": "manager", "username": "optional-username"}'
   ```
   </Info>
 </Accordion>

webdocs/cheatsheet.mdx

@@ -49,17 +49,20 @@ Quick reference for common FastSkill operations.
 
 | Operation | Command | What It Does |
 |-----------|---------|--------------|
-| List repositories | `fastskill registry list` | Lists all configured repositories from `skill-project.toml` |
-| Show repository | `fastskill registry show repo-name` | Displays repository configuration details (type, URL, auth, priority) |
-| Add repository | `fastskill registry add repo-name --type git-marketplace --url <url>` | Adds new repository to `skill-project.toml`, supports git-marketplace, http-registry, zip-url, local |
-| Remove repository | `fastskill registry remove repo-name` | Removes repository from `skill-project.toml` |
-| Create marketplace | `fastskill registry create --path ./skills` | Scans directory for skills, generates `marketplace.json` for repository distribution |
+| List repositories | `fastskill sources list` | Lists all configured repositories from `skill-project.toml` |
+| Show repository | `fastskill sources show repo-name` | Displays repository configuration details (type, URL, auth, priority) |
+| Add repository | `fastskill sources add repo-name --repo-type git-marketplace <url>` | Adds new repository to `skill-project.toml`, supports git-marketplace, http-registry, zip-url, local |
+| Remove repository | `fastskill sources remove repo-name` | Removes repository from `skill-project.toml` |
+| Update repository | `fastskill sources update repo-name --branch main --priority 1` | Updates repository metadata (branch, priority) |
+| Test repository | `fastskill sources test repo-name` | Tests repository connectivity and accessibility |
+| Refresh repositories | `fastskill sources refresh` | Refreshes repository cache (re-fetches from source) |
 | List registry skills | `fastskill registry list-skills` | Lists all skills from HTTP registry (grid format) |
 | List registry skills (JSON) | `fastskill registry list-skills --json` | Lists all skills from HTTP registry in JSON format |
 | List by scope | `fastskill registry list-skills --scope acme` | Lists skills filtered by scope from HTTP registry |
 | List all versions | `fastskill registry list-skills --all-versions` | Lists all versions of each skill from HTTP registry |
-| Show skill | `fastskill registry show-skill skill-id` | Shows details for a specific skill |
-| Search skills | `fastskill registry search query` | Searches for skills across repositories |
+| Show skill | `fastskill registry show-skill skill-id` | Shows details for a specific skill from registry |
+| Show skill versions | `fastskill registry versions skill-id` | Lists all available versions for a specific skill |
+| Search skills | `fastskill registry search query` | Searches for skills across repositories (text-only search) |
 
 For detailed documentation, see the [README](/) and [Registry Guide](/registry/overview).
 

webdocs/cli-reference/overview.mdx

@@ -60,9 +60,8 @@ fastskill list --help         # Help for list command
 |--------|-------------|---------|
 | `--version` | Show version information | `fastskill --version` |
 | `--verbose, -v` | Enable verbose output | `fastskill -v list` |
-| `--quiet, -q` | Suppress non-error output | `fastskill -q register skill.json` |
-| `--config` | Specify configuration file | `fastskill --config prod.json serve` |
-| `--log-level` | Set logging level | `fastskill --log-level DEBUG serve` |
+| `--repositories_path` | Path to repositories configuration file | `fastskill --repositories_path .claude/repositories.toml list` |
+| `--global` | Use global configuration instead of project-level | `fastskill --global list` |
 | `--help, -h` | Show help information | `fastskill --help` |
 
 ## Command Categories
@@ -117,7 +116,7 @@ fastskill list --help         # Help for list command
     Semantic search across installed skills (supports `--format xml`, `--format json`). See [search Command](/cli-reference/search-command).
   </Card>
   <Card title="fastskill sources" icon="book">
-    Manage repositories (list/add/remove/show/update/test/refresh/create) with authentication and priority. See [sources Command](/cli-reference/sources-command).
+    Manage repositories (list/add/remove/show/update/test/refresh) with authentication and priority. See [sources Command](/cli-reference/sources-command).
   </Card>
   <Card title="fastskill auth" icon="key">
     Manage authentication (login/logout/whoami) with JWT tokens and RBAC. See [auth Command](/cli-reference/auth-command).
@@ -390,7 +389,7 @@ jobs:
   </Tip>
 
   <Tip>
-  **Service permissions**: Use `--user` flag or run with appropriate privileges for system-wide operations.
+  **Service permissions**: Run with appropriate privileges for system-wide operations.
   </Tip>
 </Accordion>
 
@@ -413,11 +412,11 @@ jobs:
 Enable debug mode for detailed troubleshooting:
 
 ```bash
-# Enable debug logging
-fastskill --log-level DEBUG serve
-
 # Run with verbose output
 fastskill -v install
+
+# Use environment variable for trace-level logging
+RUST_LOG=fastskill=trace fastskill serve
 ```
 
 ## Best Practices