Skip to content

Commit c7c17bb

Browse files
robinsonrobinson
authored
Merge pull request #130 from isartor-ai/codex/docs-autofac-de-manual
[codex] Add docs.agentwerke.de manual site
2 parents ffa53ed + 5846cb0 commit c7c17bb

34 files changed

Lines changed: 4808 additions & 0 deletions

‎.github/workflows/docs-pages.yml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
name: Docs Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs.agentwerke.de/**'
8+
- '.github/workflows/docs-pages.yml'
9+
pull_request:
10+
paths:
11+
- 'docs.agentwerke.de/**'
12+
- '.github/workflows/docs-pages.yml'
13+
workflow_dispatch:
14+
15+
permissions:
16+
contents: read
17+
pages: write
18+
id-token: write
19+
20+
concurrency:
21+
group: docs-pages-${{ github.ref }}
22+
cancel-in-progress: false
23+
24+
jobs:
25+
build:
26+
runs-on: ubuntu-latest
27+
28+
steps:
29+
- name: Checkout
30+
uses: actions/checkout@v4
31+
with:
32+
fetch-depth: 0
33+
34+
- name: Setup Node
35+
uses: actions/setup-node@v4
36+
with:
37+
node-version: 20
38+
cache: npm
39+
cache-dependency-path: docs.agentwerke.de/package-lock.json
40+
41+
- name: Install dependencies
42+
run: npm ci
43+
working-directory: docs.agentwerke.de
44+
45+
- name: Build docs
46+
run: npm run build
47+
working-directory: docs.agentwerke.de
48+
49+
- name: Configure Pages
50+
if: github.event_name != 'pull_request'
51+
uses: actions/configure-pages@v4
52+
53+
- name: Upload Pages artifact
54+
if: github.event_name != 'pull_request'
55+
uses: actions/upload-pages-artifact@v3
56+
with:
57+
path: docs.agentwerke.de/.vitepress/dist
58+
59+
deploy:
60+
if: github.event_name != 'pull_request'
61+
needs: build
62+
runs-on: ubuntu-latest
63+
environment:
64+
name: github-pages
65+
url: ${{ steps.deployment.outputs.page_url }}
66+
67+
steps:
68+
- name: Deploy to GitHub Pages
69+
id: deployment
70+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,12 @@ node_modules/
2323
coverage/
2424
coverage.*
2525

26+
# Node / static site
27+
node_modules/
28+
web/dist/
29+
docs.agentwerke.de/.vitepress/cache/
30+
docs.agentwerke.de/.vitepress/dist/
31+
2632
# OS
2733
.DS_Store
2834
Thumbs.db

‎docs.agentwerke.de/.vitepress/config.ts‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
import { defineConfig } from 'vitepress';
2+
3+
export default defineConfig({
4+
lang: 'en-US',
5+
title: 'Agentwerke',
6+
description: 'User manual for governed AI software delivery with Agentwerke.',
7+
base: '/',
8+
lastUpdated: true,
9+
themeConfig: {
10+
logo: '/agentwerke-run-map.svg',
11+
siteTitle: 'Agentwerke Docs',
12+
search: {
13+
provider: 'local',
14+
},
15+
nav: [
16+
{ text: 'Start', link: '/start/quickstart' },
17+
{ text: 'Manual', link: '/manual/runs' },
18+
{ text: 'Admin', link: '/admin/deployment' },
19+
{ text: 'Developer', link: '/developer/local-development' },
20+
{ text: 'Reference', link: '/reference/bpmn-extensions' },
21+
],
22+
sidebar: [
23+
{
24+
text: 'Start Here',
25+
items: [
26+
{ text: 'What Agentwerke Is', link: '/start/what-is-agentwerke' },
27+
{ text: 'Quickstart', link: '/start/quickstart' },
28+
{ text: 'Core Concepts', link: '/start/core-concepts' },
29+
],
30+
},
31+
{
32+
text: 'User Manual',
33+
items: [
34+
{ text: 'Runs', link: '/manual/runs' },
35+
{ text: 'Approvals And Evidence', link: '/manual/approvals-evidence' },
36+
{ text: 'Model Providers', link: '/manual/model-providers' },
37+
{ text: 'GitHub Issue Trigger', link: '/manual/github-issue-trigger' },
38+
{ text: 'Workflow Authoring', link: '/manual/workflow-authoring' },
39+
{ text: 'Agents And Skills', link: '/manual/agents-skills' },
40+
],
41+
},
42+
{
43+
text: 'Administrator Guide',
44+
items: [
45+
{ text: 'Deployment', link: '/admin/deployment' },
46+
{ text: 'Settings And Secrets', link: '/admin/settings-secrets' },
47+
{ text: 'Auth And Data Residency', link: '/admin/auth-data-residency' },
48+
{ text: 'Sandboxes And Storage', link: '/admin/sandboxes-storage' },
49+
],
50+
},
51+
{
52+
text: 'Developer Guide',
53+
items: [
54+
{ text: 'Local Development', link: '/developer/local-development' },
55+
{ text: 'Architecture', link: '/developer/architecture' },
56+
{ text: 'API Overview', link: '/developer/api-overview' },
57+
{ text: 'Extending Agentwerke', link: '/developer/extending-agentwerke' },
58+
],
59+
},
60+
{
61+
text: 'Reference',
62+
items: [
63+
{ text: 'BPMN Extensions', link: '/reference/bpmn-extensions' },
64+
{ text: 'Security Model', link: '/reference/security-model' },
65+
{ text: 'Persistence Schema', link: '/reference/persistence-schema' },
66+
{ text: 'Open Core Boundary', link: '/reference/open-core' },
67+
{ text: 'Architecture Decisions', link: '/reference/architecture-decisions' },
68+
{ text: 'Docs Site Deployment', link: '/reference/docs-site-deployment' },
69+
],
70+
},
71+
],
72+
outline: {
73+
level: [2, 3],
74+
},
75+
editLink: {
76+
pattern: 'https://github.com/isartor-ai/agentwerke/edit/main/docs.agentwerke.de/:path',
77+
text: 'Edit this page on GitHub',
78+
},
79+
socialLinks: [
80+
{ icon: 'github', link: 'https://github.com/isartor-ai/agentwerke' },
81+
],
82+
footer: {
83+
message: 'Apache-2.0 open core. Enterprise-only capabilities are labeled in context.',
84+
copyright: 'Copyright 2026 Isartor AI',
85+
},
86+
},
87+
});

‎docs.agentwerke.de/.vitepress/theme/custom.css‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
:root {
2+
--vp-c-brand-1: #0f766e;
3+
--vp-c-brand-2: #0d9488;
4+
--vp-c-brand-3: #14b8a6;
5+
--vp-c-brand-soft: rgba(20, 184, 166, 0.14);
6+
--vp-c-tip-1: #0f766e;
7+
--vp-c-tip-2: #0d9488;
8+
--vp-c-warning-1: #92400e;
9+
--vp-c-warning-soft: rgba(245, 158, 11, 0.14);
10+
--vp-c-danger-1: #b91c1c;
11+
--vp-layout-max-width: 1480px;
12+
}
13+
14+
.dark {
15+
--vp-c-brand-1: #2dd4bf;
16+
--vp-c-brand-2: #14b8a6;
17+
--vp-c-brand-3: #0f766e;
18+
--vp-c-brand-soft: rgba(45, 212, 191, 0.16);
19+
}
20+
21+
.VPDoc .container {
22+
max-width: 1120px;
23+
}
24+
25+
.VPDoc h1,
26+
.VPDoc h2,
27+
.VPDoc h3 {
28+
letter-spacing: 0;
29+
}
30+
31+
.VPDoc table {
32+
font-size: 14px;
33+
}
34+
35+
.VPDoc .custom-block {
36+
border-radius: 6px;
37+
}
38+
39+
.doc-map {
40+
margin: 24px 0 32px;
41+
}
42+
43+
.doc-map img {
44+
width: 100%;
45+
max-width: 920px;
46+
border: 1px solid var(--vp-c-divider);
47+
border-radius: 8px;
48+
background: var(--vp-c-bg-soft);
49+
}
50+
51+
.manual-grid {
52+
display: grid;
53+
grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
54+
gap: 12px;
55+
margin: 24px 0;
56+
}
57+
58+
.manual-grid a {
59+
display: block;
60+
min-height: 104px;
61+
padding: 16px;
62+
border: 1px solid var(--vp-c-divider);
63+
border-radius: 8px;
64+
color: var(--vp-c-text-1);
65+
text-decoration: none;
66+
background: var(--vp-c-bg);
67+
}
68+
69+
.manual-grid a:hover {
70+
border-color: var(--vp-c-brand-2);
71+
}
72+
73+
.manual-grid strong {
74+
display: block;
75+
margin-bottom: 6px;
76+
}
77+
78+
.manual-grid span {
79+
color: var(--vp-c-text-2);
80+
font-size: 14px;
81+
line-height: 1.5;
82+
}

‎docs.agentwerke.de/.vitepress/theme/index.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
import DefaultTheme from 'vitepress/theme';
2+
import './custom.css';
3+
4+
export default DefaultTheme;

‎docs.agentwerke.de/admin/auth-data-residency.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Auth And Data Residency
2+
3+
Agentwerke protects product APIs with JWT bearer authentication and role-based authorization. Health probes, auth discovery/dev-token endpoints, and signed integration webhooks remain anonymous by design.
4+
5+
## Authentication modes
6+
7+
### Enterprise OIDC/JWT
8+
9+
Configure the API to validate tokens from your identity provider.
10+
11+
Microsoft Entra ID example:
12+
13+
```bash
14+
Jwt__Authority=https://login.microsoftonline.com/<tenant-id>/v2.0
15+
Jwt__Audience=api://agentwerke
16+
```
17+
18+
Keycloak example:
19+
20+
```bash
21+
Jwt__Authority=https://keycloak.example.com/realms/<realm>
22+
Jwt__Audience=agentwerke-api
23+
```
24+
25+
Agentwerke normalizes role claims from `role`, `roles`, `groups`, and the standard .NET role claim type. Configure additional claim names when needed:
26+
27+
```bash
28+
Jwt__RoleClaimTypes__0=roles
29+
Jwt__RoleClaimTypes__1=groups
30+
Jwt__NameClaimTypes__0=preferred_username
31+
Jwt__NameClaimTypes__1=email
32+
```
33+
34+
Map external groups to Agentwerke roles:
35+
36+
```bash
37+
Jwt__RoleMappings__agentwerke_viewers__0=Viewer
38+
Jwt__RoleMappings__agentwerke_operators__0=Operator
39+
Jwt__RoleMappings__agentwerke_approvers__0=Approver
40+
Jwt__RoleMappings__agentwerke_admins__0=Admin
41+
```
42+
43+
### Symmetric JWT for local stacks
44+
45+
Local and manual-test stacks can use a development signing key:
46+
47+
```bash
48+
Jwt__SecretKey=agentwerke-dev-manual-testing-key-2026
49+
Jwt__Issuer=agentwerke-dev
50+
Jwt__Audience=agentwerke-dev
51+
Jwt__DevTokensEnabled=true
52+
```
53+
54+
Do not enable development tokens in production.
55+
56+
### Development identity mode
57+
58+
`appsettings.Development.json` can authenticate requests without a bearer token as `dev:admin` when `ASPNETCORE_ENVIRONMENT=Development`. Disable this in shared development environments that need explicit bearer tokens:
59+
60+
```bash
61+
Jwt__DevIdentityEnabled=false
62+
```
63+
64+
## Roles
65+
66+
| Role | Access |
67+
| --- | --- |
68+
| `Viewer` | Read workflows, runs, approvals, templates, agents, and skills. |
69+
| `Operator` | Viewer access plus workflow import/validation, run start/cancel/recover, policy simulation, and artifact upload. |
70+
| `Approver` | Viewer access plus approval decisions. |
71+
| `Admin` | Operator and approver access plus workflow publish, settings, and policy-rule management. |
72+
73+
## Data residency boundaries
74+
75+
The default self-hosted deployment keeps workflow definitions, runs, approvals, audit records, run context, and outbox state in the configured PostgreSQL database.
76+
77+
Artifact bytes stay in the configured storage provider:
78+
79+
| Provider | Boundary |
80+
| --- | --- |
81+
| `filesystem` | Files under `Storage:RootPath`. |
82+
| `s3` | Bucket and region configured by the operator. |
83+
84+
The default `WorkflowRuntime:Mode=Agentwerke` does not require Camunda. Camunda settings are consumed only when `WorkflowRuntime:Mode=Camunda`.
85+
86+
## External data flows
87+
88+
Data leaves the self-hosted boundary only through explicitly enabled integrations and model providers:
89+
90+
- GitHub, Jira, Slack, and Teams connectors.
91+
- Model-provider endpoints.
92+
- Artifact storage if it is outside the host or cluster.
93+
- Telemetry endpoints such as OTLP collectors.
94+
95+
For German or EU residency requirements, choose customer-approved regions for Postgres, artifacts, and model endpoints, and verify connector tenant boundaries.
96+
97+
## Production checklist
98+
99+
- Disable dev identity and dev tokens.
100+
- Use real JWT/OIDC authority and audience settings.
101+
- Map enterprise roles deliberately.
102+
- Store identity-provider secrets outside the repository.
103+
- Document the configured data boundary.
104+
- Review enabled integrations before production traffic.
105+
- Confirm evidence packs do not contain unexpected sensitive content.

0 commit comments

Comments
 (0)