README.md

Graftcode documentation

Documentation (this site) explains concepts, procedures, reference material, operations, and troubleshooting. Quick start on the same site contains hands-on tutorials (expose a backend, connect a frontend, connect microservices, and more). Run Quick start first for your stack; return here when you need to understand why something works or what to do in production.

Start here

1. Quick start — first working call (hands-on).
2. What is Graftcode? — definition, before/after, and use cases.
3. How Graftcode works — the How it works diagram and mental model.
4. Choose your scenario — pick your goal, then your runtime.
5. Quick Reference — bookmark while coding.
6. Where does Graftcode fit?.

Core concepts

1. What is a Graft?
2. Callable surface
3. Public surface vs implementation
4. Caller and receiver
5. Static and instance context
6. Gateway and hosted modules
7. Hypertube runtime bridge
8. Graftcode Vision
9. Invocation lifecycle
10. In-memory, same-machine, and remote execution
11. Configuration resolution
12. Package generation
13. Type mapping
14. Contract evolution
15. Core-concepts glossary
16. Graftcode context

How-to guides

• Expose code as a Graftcode Receiver
• Obtain and install a Graft
• Configure Graft invocation
• Run Gateway locally
• Deploy Gateway with Docker
• Use a portal project key
• Gateway module versioning and --noVersioning
• Filter the callable surface
• Expose Receiver methods for MCP
• Authenticate Graft calls
• Stateless vs stateful Graft calls
• Set the module path for in-memory execution
• Use Graftcode alongside an existing REST API
• Debug Graft invocations
• Handle Receiver errors
• Update a Receiver contract
• Dependency injection with stateless facades

Authoring multi-runtime snippets

Use one file with multi code fences when only code differs by runtime (how-to guides, reference shortcuts, operations, troubleshooting). The portal renders a tab picker inside each snippet (.NET, JavaScript, Python, Java, PHP, Ruby) instead of a page-level stack picker:

```multi
```dotnet
// .NET example
```
```javascript
// Node example
```
```python
# Python example
```
```java
// Java example
```
```php
// PHP example
```
```ruby
# Ruby example
```
```

Use a folder per runtime (how-to-guides/<slug>/dotnet.md, …) only when prose or steps materially differ by stack. Regenerate consolidated guides with scripts/consolidate-howto-articles.py.

Operations

• Operations and deployment model
• Gateway lifecycle
• Environment and configuration
• Authentication and authorization operations
• Networking and ports
• Health checks
• Logging, metrics, and tracing
• Timeouts and retries
• Scaling Gateway Receivers
• Version compatibility and upgrades

Reference

• Quick Reference
• Quick start courses
• Project Key, registry, host, and credentials
• Gateway CLI reference
• Configuration keys and precedence
• Environment variable reference
• Supported runtimes and package managers
• Type compatibility matrix
• Errors and status reference
• Generated package structure
• Ports and protocols reference
• Known limitations

Troubleshooting

• Troubleshooting
• Package installation fails
• Module, method, or type is missing
• Connection, timeout, or authentication failure
• Installed package is stale
• Gateway or runtime exits
• Vision and runtime disagree
• In-memory execution and Hypertube exceptions

Machine-readable navigation

categories:
  - name: "Start here"
    order: 1
    path: "introduction"
    items:
      - title: "What is Graftcode?"
        path: "introduction/what-is-graftcode.md"
        order: 1
      - title: "How Graftcode works"
        path: "introduction/how-graftcode-works.md"
        order: 2
      - title: "Choose your scenario"
        path: "introduction/choose-your-scenario.md"
        order: 3
      - title: "Where does Graftcode fit?"
        path: "introduction/where-does-graftcode-fit.md"
        order: 4
  - name: "Core concepts"
    order: 2
    path: "core-concepts"
    items:
      - title: "What is a Graft?"
        path: "core-concepts/what-is-a-graft.md"
        order: 1
      - title: "Callable surface"
        path: "core-concepts/callable-surface.md"
        order: 2
      - title: "Public surface vs implementation"
        path: "core-concepts/public-surface-vs-implementation.md"
        order: 3
      - title: "Caller and receiver"
        path: "core-concepts/caller-and-receiver.md"
        order: 4
      - title: "Static and instance context"
        path: "core-concepts/static-and-instance-context.md"
        order: 5
      - title: "Gateway and hosted modules"
        path: "core-concepts/gateway-and-hosted-modules.md"
        order: 6
      - title: "Hypertube runtime bridge"
        path: "core-concepts/hypertube-runtime-bridge.md"
        order: 7
      - title: "Graftcode Vision"
        path: "core-concepts/graftcode-vision.md"
        order: 8
      - title: "Invocation lifecycle"
        path: "core-concepts/invocation-lifecycle.md"
        order: 9
      - title: "In-memory, same-machine, and remote execution"
        path: "core-concepts/in-memory-same-machine-and-remote-execution.md"
        order: 10
      - title: "Configuration resolution"
        path: "core-concepts/configuration-resolution.md"
        order: 11
      - title: "Package generation"
        path: "core-concepts/package-generation.md"
        order: 12
      - title: "Type mapping"
        path: "core-concepts/type-mapping.md"
        order: 13
      - title: "Contract evolution"
        path: "core-concepts/contract-evolution.md"
        order: 14
      - title: "Core-concepts glossary"
        path: "core-concepts/core-concepts-glossary.md"
        order: 15
      - title: "Graftcode Context library"
        path: "core-concepts/graftcode-context.md"
        order: 16
  - name: "How-to guides"
    order: 3
    path: "how-to-guides"
    items:
      - title: "Expose code as a Graftcode Receiver"
        path: "how-to-guides/expose-code-as-a-graftcode-receiver.md"
        order: 1
      - title: "Obtain and install a Graft"
        path: "how-to-guides/obtain-and-install-a-graft.md"
        order: 2
      - title: "Configure Graft invocation"
        path: "how-to-guides/configure-graft-invocation.md"
        order: 3
      - title: "Run Gateway locally"
        path: "how-to-guides/run-gateway-locally.md"
        order: 4
      - title: "Deploy Gateway with Docker"
        path: "how-to-guides/deploy-gateway-with-docker.md"
        order: 5
      - title: "Use a portal project key"
        path: "how-to-guides/use-a-portal-project-key.md"
        order: 6
      - title: "Gateway module versioning and --noVersioning"
        path: "how-to-guides/gateway-module-versioning-and-noversioning.md"
        order: 7
      - title: "Filter the callable surface"
        path: "how-to-guides/filter-the-callable-surface.md"
        order: 8
      - title: "Expose Receiver methods for MCP"
        path: "how-to-guides/expose-receiver-methods-for-mcp.md"
        order: 9
      - title: "Authenticate Graft calls"
        path: "how-to-guides/authenticate-graft-calls.md"
        order: 10
      - title: "Stateless vs stateful Graft calls"
        path: "how-to-guides/stateless-vs-stateful-graft-calls.md"
        order: 11
      - title: "Set the module path for in-memory execution"
        path: "how-to-guides/set-the-module-path-for-in-memory-execution.md"
        order: 12
      - title: "Use Graftcode alongside an existing REST API"
        path: "how-to-guides/use-graftcode-alongside-an-existing-rest-api.md"
        order: 13
      - title: "Debug Graft invocations"
        path: "how-to-guides/debug-graft-invocations.md"
        order: 14
      - title: "Handle Receiver errors"
        path: "how-to-guides/handle-receiver-errors.md"
        order: 15
      - title: "Update a Receiver contract"
        path: "how-to-guides/update-a-receiver-contract.md"
        order: 16
      - title: "Dependency injection with stateless facades"
        path: "how-to-guides/dependency-injection-with-stateless-facades.md"
        order: 17
  - name: "Operations"
    order: 4
    path: "operations"
    items:
      - title: "Operations and deployment model"
        path: "operations/operations-and-deployment-model.md"
        order: 1
      - title: "Gateway lifecycle"
        path: "operations/gateway-lifecycle.md"
        order: 2
      - title: "Environment and configuration"
        path: "operations/environment-and-configuration.md"
        order: 3
      - title: "Authentication and authorization operations"
        path: "operations/authentication-and-authorization-operations.md"
        order: 4
      - title: "Networking and ports"
        path: "operations/networking-and-ports.md"
        order: 5
      - title: "Health checks"
        path: "operations/health-checks.md"
        order: 6
      - title: "Logging, metrics, and tracing"
        path: "operations/logging-metrics-and-tracing.md"
        order: 7
      - title: "Timeouts and retries"
        path: "operations/timeouts-and-retries.md"
        order: 8
      - title: "Scaling Gateway Receivers"
        path: "operations/scaling-gateway-receivers.md"
        order: 9
      - title: "Version compatibility and upgrades"
        path: "operations/version-compatibility-and-upgrades.md"
        order: 10
  - name: "Reference"
    order: 5
    path: "reference"
    items:
      - title: "Quick Reference"
        path: "reference/quick-reference.md"
        order: 1
      - title: "Quick start courses"
        path: "reference/quick-start-courses.md"
        order: 2
      - title: "Project Key, registry, host, and credentials"
        path: "reference/project-key-registry-host-and-credentials.md"
        order: 3
      - title: "Gateway CLI reference"
        path: "reference/gateway-cli-reference.md"
        order: 4
      - title: "Configuration keys and precedence"
        path: "reference/configuration-keys-and-precedence.md"
        order: 5
      - title: "Environment variable reference"
        path: "reference/environment-variable-reference.md"
        order: 6
      - title: "Supported runtimes and package managers"
        path: "reference/supported-runtimes-and-package-managers.md"
        order: 7
      - title: "Type compatibility matrix"
        path: "reference/type-compatibility-matrix.md"
        order: 8
      - title: "Errors and status reference"
        path: "reference/errors-and-status-reference.md"
        order: 9
      - title: "Generated package structure"
        path: "reference/generated-package-structure.md"
        order: 10
      - title: "Ports and protocols reference"
        path: "reference/ports-and-protocols-reference.md"
        order: 11
      - title: "Known limitations"
        path: "reference/known-limitations.md"
        order: 12
  - name: "Troubleshooting"
    order: 6
    path: "troubleshooting"
    items:
      - title: "Troubleshooting"
        path: "troubleshooting/troubleshooting.md"
        order: 1
      - title: "Package installation fails"
        path: "troubleshooting/package-installation-fails.md"
        order: 2
      - title: "Module, method, or type is missing"
        path: "troubleshooting/module-method-or-type-is-missing.md"
        order: 3
      - title: "Connection, timeout, or authentication failure"
        path: "troubleshooting/connection-timeout-or-authentication-failure.md"
        order: 4
      - title: "Installed package is stale"
        path: "troubleshooting/installed-package-is-stale.md"
        order: 5
      - title: "Gateway or runtime exits"
        path: "troubleshooting/gateway-or-runtime-exits.md"
        order: 6
      - title: "Vision and runtime disagree"
        path: "troubleshooting/vision-and-runtime-disagree.md"
        order: 7
      - title: "In-memory execution and Hypertube exceptions"
        path: "troubleshooting/in-memory-hypertube-exceptions.md"
        order: 8