Chore/sync wiki

src/main/resources/wiki/FAQ.md

@@ -445,6 +445,31 @@ exposes:
 
 MCP clients can then discover and use these resources dynamically.
 
+### Q: Can I create MCP tools that return static mock data?
+**A:** Yes, starting in version 1.0.0 Alpha 2. Define `outputParameters` with `const` values and omit `call` and `steps`. The tool serves a fixed JSON response — no `consumes` block is needed:
+
+```yaml
+exposes:
+  - type: mcp
+    port: 3001
+    namespace: mock-tools
+    description: Mock MCP server
+    tools:
+      - name: say-hello
+        description: Returns a greeting
+        inputParameters:
+          - name: name
+            type: string
+            required: true
+            description: Name to greet
+        outputParameters:
+          - name: message
+            type: string
+            const: "Hello, World!"
+```
+
+This mirrors the REST mock pattern (`no-adapter.yml`) and is useful for prototyping, demos, and contract-first development.
+
 ---
 
 ## 🔭 Troubleshooting & Debugging

src/main/resources/wiki/Guide-Linting.md → src/main/resources/wiki/Guide-‐-Linting.md

@@ -32,7 +32,7 @@ Both tools can be run standalone or orchestrated together via [MegaLinter](https
 
 > **JSON Schema** catches "is this valid YAML?", **Spectral** catches "is this *good* YAML?"
 
-For a full reference of all Spectral rules, see the [Ruleset](https://github.com/naftiko/framework/wiki/Ruleset) page.
+For a full reference of all Spectral rules, see the [Ruleset](https://github.com/naftiko/framework/wiki/Specification-%E2%80%90-Rules) page.
 
 ---
 
@@ -206,7 +206,7 @@ Catches semantic and style issues such as:
 | **Quality** | Missing `description` on consumes entries, REST resources, or operations |
 | **Security** | `<script>` tags or `eval(` in description fields |
 
-For the full list, see the [Specification - Rules](https://github.com/naftiko/framework/wiki/Specification-Rules) page.
+For the full list, see the [Specification - Rules](https://github.com/naftiko/framework/wiki/Specification-%E2%80%90-Rules) page.
 
 ---
 

src/main/resources/wiki/Guide-Use-Cases.md → src/main/resources/wiki/Guide-‐-Use-Cases.md

@@ -13,6 +13,19 @@ How Naftiko achieves this technically:
 
 ![Integrate AI](https://naftiko.github.io/docs/images/technology/use_case_AI_integration.png)
 
+#### Key features
+- [x] Declarative HTTP consumption with namespace-scoped adapters
+  - [x] Bearer, API key, basic, and digest authentication
+  - [x] Templated baseUri and path parameters
+- [x] Polyglot exposure from one capability
+  - [x] Agent skills exposure for AI agents
+  - [x] MCP tool exposure for AI agents
+  - [x] REST resource exposure for conventional clients
+- [x] Output shaping with typed parameters and JSONPath mapping
+  - [x] Nested object and array output parameters
+  - [x] Const values for computed fields
+- [x] Externalized secrets via `binds` (file, vault, environment)
+
 ## 2. Rightsize AI context
 
 Expose only the context an AI task needs, reducing noise, improving relevance, and keeping prompts efficient.
@@ -25,11 +38,16 @@ How Naftiko achieves this technically:
 ![Rightsize AI context](https://naftiko.github.io/docs/images/technology/use_case_context_engineering_rightsize_ai_context.png)
 
 #### Key features
-- [x] Declarative applied capability exposing MCP              
+- [x] Declarative applied capability exposing MCP
   - [x] Declarative applied capabilities with reused source capabilities
 - [x] Support for key MCP transport protocols
   - [x] MCP for Streaming HTTP (for remote MCP clients)
   - [x] MCP for Standard IO (for local MCP clients)
+- [x] Output shaping with typed parameters and JSONPath mapping
+  - [x] Fine-grained field selection and nested object mapping
+  - [x] Const values to inject static context
+- [x] Typed MCP tool input parameters with descriptions
+  - [x] Required/optional parameter declarations for agent discovery
 
 ## 3. Elevate an existing API
 
@@ -50,7 +68,11 @@ How Naftiko achieves this technically:
   - [x] Focus on source APIs with JSON payloads
   - [x] Change HTTP methods to expose proper semantics
     - E.g. Adapt read-only POST queries into cacheable GET queries
-  - [x] Convert XML, Avro, CSV payloads to JSON
+  - [x] Convert XML, Avro, CSV, YAML, and Protobuf payloads to JSON
+- [x] Schema-based validation with Spectral rules
+  - [x] Namespace uniqueness, path conventions, and security checks
+- [x] Forward proxy for selective pass-through routing
+  - [x] Trusted header forwarding
 
 ## 4. Elevate Google Sheets API
 
@@ -87,8 +109,15 @@ How Naftiko achieves this technically:
 
 #### Key features
 - [x] Declarative source HTTP adapter and target MCP adapter
-- [x] Support for source capabilities
+- [x] Support for multiple consumed adapters with unique namespaces
   - [x] Reuse consistent APIs and JSON payloads
+- [x] Multi-step orchestration with ordered steps
+  - [x] Call steps to invoke consumed operations
+  - [x] Lookup steps for in-memory data joining
+  - [x] Step output bridging via `with` and `mappings`
+- [x] Composed output model from cross-source data
+  - [x] Named orchestrated output parameters
+  - [x] Nested objects and typed arrays
 
 ## 6. Rightsize a set of microservices
 
@@ -103,9 +132,14 @@ How Naftiko achieves this technically:
 
 #### Key features
 - [x] Declarative source HTTP adapter and target REST adapter
-  - [x] Finish support for source APIs with JSON payloads
-    - [x] Convert YAML, Protobuf, payloads to JSON
-    - [x] Support sequence of steps with calls
+  - [x] Support for source APIs with JSON payloads
+  - [x] Convert YAML, Protobuf, XML, Avro, and CSV payloads to JSON
+  - [x] Support sequence of steps with calls
+- [x] Multiple consumed adapters per capability
+  - [x] Namespace-scoped auth, headers, and base URI per adapter
+- [x] Unified parameter handling across microservices
+  - [x] Input parameters in query, header, path, cookie, and body
+  - [x] Regex pattern validation on string inputs
 
 ## 7. Rightsize a monolith API
 
@@ -118,6 +152,17 @@ How Naftiko achieves this technically:
 
 ![Rightsize monolith APIs](https://naftiko.github.io/docs/images/technology/use_case_api_reusability_rightsize_monolith_apis.png)
 
+#### Key features
+- [x] Selective operation exposure from a broad API
+  - [x] Remap consumed operations to narrower exposed resources
+  - [x] Output filtering via typed parameters and JSONPath mapping
+- [x] Forward proxy for pass-through routes
+  - [x] `forward.targetNamespace` for direct routing
+  - [x] Trusted header forwarding for security
+- [x] Dual-channel exposure from one capability
+  - [x] REST resource exposure for conventional clients
+  - [x] MCP tool exposure for AI agents
+
 ## 8. Capability-first context engineering
 
 Design capabilities first for MCP clients, then map them to underlying APIs for a clean AI-native integration model.
@@ -130,9 +175,17 @@ How Naftiko achieves this technically:
 ![Capability-first approach](https://naftiko.github.io/docs/images/technology/use_case_context_engineering_capability_first.png)
 
 #### Key features
-- [x] Declarative target API contract with mocking mode
-  - [x] Allow REST server adapter with no source HTTP adapter
-  - [x] Use static value of output parameters as sample
+- [x] Declarative MCP server with tools, resources, and prompts
+  - [x] Typed input parameters with descriptions for agent discovery
+  - [x] Static file-backed resources with MIME types
+  - [x] Prompt templates with argument placeholders
+- [x] Support for key MCP transport protocols
+  - [x] MCP for Streaming HTTP (for remote MCP clients)
+  - [x] MCP for Standard IO (for local MCP clients)
+- [x] Mock mode for MCP tools
+  - [x] Static const-valued outputs without consuming an API
+- [x] Multi-step orchestration wired to consumed operations
+  - [x] Call and lookup steps with cross-step output bridging
 
 ## 9. Capability-first API reusability
 
@@ -144,3 +197,16 @@ How Naftiko achieves this technically:
 - Add format-aware parsing and mapping (JSON, YAML, XML, CSV, Avro, Protobuf support in the framework) to normalize diverse backends.
 
 ![Capability-first approach](https://naftiko.github.io/docs/images/technology/use_case_api_reusability_capability_first.png)
+
+#### Key features
+- [x] Externalized secrets via `binds`
+  - [x] Support for file, vault, GitHub secrets, K8s secrets, and runtime injection
+  - [x] SCREAMING_SNAKE_CASE variable expressions
+- [x] Consumes import and reuse across capabilities
+  - [x] Import by location with optional namespace aliasing
+- [x] Format-aware response parsing and normalization
+  - [x] JSON, XML, YAML, CSV, Avro, and Protobuf to JSON conversion
+- [x] Multiple request body formats
+  - [x] JSON, XML, form URL encoded, multipart form
+- [x] Incremental adapter addition (REST, MCP, or Skill)
+  - [x] Skill server exposure with agent-compatible metadata

src/main/resources/wiki/Installation.md

@@ -25,13 +25,13 @@ To use Naftiko Framework, you must install and then run its engine.
 
 ### Configure your own capability
 * Create your capability configuration file.\
-  The Naftiko Engine runs capabilities. For that, it uses a capability configuration file. You first have to create this file locally. You can use [this first Shipyard example](https://github.com/naftiko/framework/blob/main/src/main/resources/tutorial/step-1-shipyard-first-capability.yml) to start with, continue with [Tutorial - Part 1](https://github.com/naftiko/framework/wiki/Tutorial-MCP-Part-1) and [Tutorial - Part 2](https://github.com/naftiko/framework/wiki/Tutorial-MCP-Part-2), and then move to the comprehensive [Specification - Schema](https://github.com/naftiko/framework/wiki/Specification-Schema) and [Specification - Rules](https://github.com/naftiko/framework/wiki/Specification-Rules). This file must be a YAML file (yaml and yml extensions are supported).
+  The Naftiko Engine runs capabilities. For that, it uses a capability configuration file. You first have to create this file locally. You can use [this first Shipyard example](https://raw.githubusercontent.com/naftiko/framework/refs/tags/v1.0.0-alpha1/src/main/resources/tutorial/step-1-shipyard-first-capability.yml) to start with, continue with [Tutorial - Part 1](https://github.com/naftiko/framework/wiki/Tutorial-%E2%80%90-Part-1) and [Tutorial - Part 2](https://github.com/naftiko/framework/wiki/Tutorial-%E2%80%90-Part-2), and then move to the comprehensive [Specification - Schema](https://github.com/naftiko/framework/wiki/Specification-%E2%80%90-Schema) and [Specification - Rules](https://github.com/naftiko/framework/wiki/Specification-%E2%80%90-Rules). This file must be a YAML file (yaml and yml extensions are supported).
 
 * Localhost in your capability configuration file.
-  * If your capability reffers to some local hosts, be carefull to not use 'localhost', but 'host.docker.internal' instead. This is because your capability will run into an isolated docker container, so 'localhost' will reffer to the container and not your local machine.\
+  * If your capability refers to some local hosts, be careful to not use 'localhost', but 'host.docker.internal' instead. This is because your capability will run into an isolated docker container, so 'localhost' will refer to the container and not your local machine.\
     For example:
     ```bash
-    baseUri: "http://host.docker.internal:8080/api"
+    baseUri: "http://host.docker.internal:8080/api/"
     ```
   * In the same way, if your capability expose a local host, be careful to not use 'localhost', but '0.0.0.0' instead. Else requests to localhost coming from outside of the container won't succeed.\
     For example:

src/main/resources/wiki/Releases.md

@@ -2,6 +2,6 @@
 | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- |
 | [0.4](https://github.com/naftiko/framework/releases/tag/v0.4)  | 2026-03-03  | 2026-03-17 | Java 21 LTS | Sept. 2028 | io.naftiko | GitHub Packages | GitHub Packages |
 | [0.5](https://github.com/naftiko/framework/releases/tag/v0.5) | 2026-03-17 | 2026-03-30 * | Java 21 LTS | Sept. 2028 | io.naftiko | GitHub Packages | GitHub Packages |
-| 1.0 Alpha 1 * | 2026-04-01 * | TBC | Java 21 LTS | Sept. 2028 | io.naftiko | Maven Central | Docker Hub |
+| [1.0 Alpha 1](https://github.com/naftiko/framework/releases/tag/v1.0.0-alpha1) | 2026-04-01 * | TBC | Java 21 LTS | Sept. 2028 | io.naftiko | Maven Central | Docker Hub |
 
 \* Future release

src/main/resources/wiki/Tutorial-Part-1.md → src/main/resources/wiki/Tutorial-‐-Part-1.md

@@ -14,7 +14,7 @@ No code. Just a spec. Let's go.
 
 **`step-1-shipyard-first-capability.yml`**
 
-> 📥 [step-1-shipyard-first-capability.yml](../tutorial/step-1-shipyard-first-capability.yml)
+> 📥 [step-1-shipyard-first-capability.yml](https://raw.githubusercontent.com/naftiko/framework/refs/tags/v1.0.0-alpha1/src/main/resources/tutorial/step-1-shipyard-first-capability.yml)
 
 The Maritime Registry at `registry.shipyard.dev` has a REST endpoint: `GET /ships`. It returns a list of ships. We want an agent to be able to call it. That's it — the absolute minimum.
 
@@ -70,7 +70,7 @@ That's your first tool. `consumes` declares where the data lives, `exposes` decl
 
 **`step-2-shipyard-input-parameters.yml`**
 
-> 📥 [step-2-shipyard-input-parameters.yml](../tutorial/step-2-shipyard-input-parameters.yml)
+> 📥 [step-2-shipyard-input-parameters.yml](https://raw.githubusercontent.com/naftiko/framework/refs/tags/v1.0.0-alpha1/src/main/resources/tutorial/step-2-shipyard-input-parameters.yml)
 
 An agent that can only list *all* ships isn't very useful. We need two things: a way to **filter** the list (by status), and a way to **look up** a specific ship (by IMO number).
 
@@ -104,7 +104,7 @@ Now the agent can ask: *"Show me only the active ships"* and *"Tell me about the
 
 **`step-3-shipyard-auth-and-binds.yml`**
 
-> 📥 [step-3-shipyard-auth-and-binds.yml](../tutorial/step-3-shipyard-auth-and-binds.yml)
+> 📥 [step-3-shipyard-auth-and-binds.yml](https://raw.githubusercontent.com/naftiko/framework/refs/tags/v1.0.0-alpha1/src/main/resources/tutorial/step-3-shipyard-auth-and-binds.yml)
 
 So far, we've been hitting the registry's **public endpoints** — they return 5 basic fields per ship. But the registry has much more: specs, dimensions, tonnage, crew assignments, certifications. That data sits behind a bearer token.
 
@@ -148,7 +148,7 @@ REGISTRY_VERSION: "2024-01-01"
 
 **`step-4-shipyard-output-shaping.yml`**
 
-> 📥 [step-4-shipyard-output-shaping.yml](../tutorial/step-4-shipyard-output-shaping.yml)
+> 📥 [step-4-shipyard-output-shaping.yml](https://raw.githubusercontent.com/naftiko/framework/refs/tags/v1.0.0-alpha1/src/main/resources/tutorial/step-4-shipyard-output-shaping.yml)
 
 Now `get-ship` returns everything: year built, gross tonnage, length overall, beam, draft, classification society, certifications, crew assignments… An agent asking *"tell me about Northern Star"* doesn't need 30 fields. It needs a **ship card**.
 
@@ -210,7 +210,9 @@ The `specs` nested object is the key: `mapping: $.dimensions.length_overall` rea
 
 **`step-5-shipyard-multi-source.yml`** — Consumes: `shared/step5-registry-consumes.yaml`, `shared/legacy-consumes.yaml`
 
-> 📥 [step-5-shipyard-multi-source.yml](../tutorial/step-5-shipyard-multi-source.yml)
+> 📥 [step-5-shipyard-multi-source.yml](https://raw.githubusercontent.com/naftiko/framework/refs/tags/v1.0.0-alpha1/src/main/resources/tutorial/step-5-shipyard-multi-source.yml)
+> 📥 [step5-registry-consumes.yaml](https://raw.githubusercontent.com/naftiko/framework/refs/tags/v1.0.0-alpha1/src/main/resources/tutorial/shared/step5-registry-consumes.yaml)
+> 📥 [legacy-consumes.yaml](https://raw.githubusercontent.com/naftiko/framework/refs/tags/v1.0.0-alpha1/src/main/resources/tutorial/shared/legacy-consumes.yaml)
 
 Data rarely lives in one place. The Shipyard's modern registry is clean, but there's also a **legacy Dockyard** — an older system with records for vessels that were never migrated. Different API, different auth (API key instead of bearer), different field names.
 
@@ -259,7 +261,9 @@ New tool: `list-legacy-vessels` — same pattern as `list-ships`, different sour
 
 **`step-6-shipyard-write-operations.yml`** — Consumes: `shared/step6-registry-consumes.yaml`, `shared/legacy-consumes.yaml`
 
-> 📥 [step-6-shipyard-write-operations.yml](../tutorial/step-6-shipyard-write-operations.yml)
+> 📥 [step-6-shipyard-write-operations.yml](https://raw.githubusercontent.com/naftiko/framework/refs/tags/v1.0.0-alpha1/src/main/resources/tutorial/step-6-shipyard-write-operations.yml)
+> 📥 [step6-registry-consumes.yaml](https://raw.githubusercontent.com/naftiko/framework/refs/tags/v1.0.0-alpha1/src/main/resources/tutorial/shared/step6-registry-consumes.yaml)
+> 📥 [legacy-consumes.yaml](https://raw.githubusercontent.com/naftiko/framework/refs/tags/v1.0.0-alpha1/src/main/resources/tutorial/shared/legacy-consumes.yaml)
 
 Until now, every tool was read-only. List, get, inspect. But Captain Erik Lindström wants to **plan a voyage** — Oslo to Singapore, aboard the Northern Star, with his crew and cargo. The agent needs to *act*.
 
@@ -321,7 +325,9 @@ The agent went from observer to operator.
 
 **`step-7-shipyard-orchestrated-lookup.yml`** — Consumes: `shared/step7-registry-consumes.yml`, `shared/legacy-consumes.yaml`
 
-> 📥 [step-7-shipyard-orchestrated-lookup.yml](../tutorial/step-7-shipyard-orchestrated-lookup.yml)
+> 📥 [step-7-shipyard-orchestrated-lookup.yml](https://raw.githubusercontent.com/naftiko/framework/refs/tags/v1.0.0-alpha1/src/main/resources/tutorial/step-7-shipyard-orchestrated-lookup.yml)
+> 📥 [step7-registry-consumes.yaml](https://raw.githubusercontent.com/naftiko/framework/refs/tags/v1.0.0-alpha1/src/main/resources/tutorial/shared/step7-registry-consumes.yaml)
+> 📥 [legacy-consumes.yaml](https://raw.githubusercontent.com/naftiko/framework/refs/tags/v1.0.0-alpha1/src/main/resources/tutorial/shared/legacy-consumes.yaml)
 
 Captain Erik is planning Oslo → Singapore. He insists on his cook: *"No Aiko, no departure."* The agent calls `get-ship` — but gets `assignedCrew: ["CREW-001", "CREW-003"]`. Raw IDs. Useless. Who is CREW-003? The captain needs *names*.
 
@@ -399,4 +405,4 @@ All from one spec. No code. Welcome to Spec-Driven Integration.
 
 Ready to expose your tools as **agent skills**, add a **REST front door**, and assemble a full **Fleet Manifest** with multi-step orchestration?
 
-Continue with the [Tutorial - Part 2](Tutorial-MCP-Part-2).
+Continue with the [Tutorial - Part 2](Tutorial-%E2%80%90-Part-2).