Skip to content

Commit 3fd3933

Browse files
ashsoleiashsolei
committed
Re-apply iAiFy overlay after upstream sync
2 parents cf864c3 + 355d845 commit 3fd3933

239 files changed

Lines changed: 32866 additions & 12376 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/debug-openshell-cluster/SKILL.md‎

Lines changed: 417 additions & 0 deletions
Large diffs are not rendered by default.

‎.agents/skills/update-docs/SKILL.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
---
2+
name: update-docs-from-commits
3+
description: Scan recent git commits for changes that affect user-facing behavior, then draft or update the corresponding documentation pages. Use when docs have fallen behind code changes, after a batch of features lands, or when preparing a release. Trigger keywords - update docs, draft docs, docs from commits, sync docs, catch up docs, doc debt, docs behind, docs drift.
4+
---
5+
6+
# Update Docs from Commits
7+
8+
Scan recent git history for commits that affect user-facing behavior and draft documentation updates for each.
9+
10+
## Prerequisites
11+
12+
- You must be in the OpenShell git repository.
13+
- The published docs tree must exist under `docs/`.
14+
- Read `docs/CONTRIBUTING.mdx` before writing any content. It contains the current style guide and formatting rules.
15+
16+
## When to Use
17+
18+
- After a batch of features or fixes has landed and docs may be stale.
19+
- Before a release, to catch any doc gaps.
20+
- When a contributor asks "what docs need updating?"
21+
22+
## Step 1: Identify Relevant Commits
23+
24+
Determine the commit range. The user may provide one explicitly (e.g., "since v0.2.0" or "last 30 commits"). If not, default to commits since the head of the main branch.
25+
26+
```bash
27+
# Commits since a tag
28+
git log v0.2.0..HEAD --oneline --no-merges
29+
30+
# Or last 50 commits
31+
git log -50 --oneline --no-merges
32+
```
33+
34+
Filter to commits that are likely to affect docs. Look for these signals:
35+
36+
1. **Commit type**: `feat`, `fix`, `refactor`, `perf` commits often change behavior. `docs` commits are already doc changes. `chore`, `ci`, `test` commits rarely need doc updates.
37+
2. **Files changed**: Changes to `crates/openshell-cli/`, `python/`, `proto/`, `deploy/`, or policy-related code are high-signal.
38+
3. **Ignore**: Changes limited to `tests/`, `e2e/`, `.github/`, `tasks/`, or internal-only modules.
39+
40+
```bash
41+
# Show files changed per commit to assess impact
42+
git log v0.2.0..HEAD --oneline --no-merges --name-only
43+
```
44+
45+
## Step 2: Map Commits to Doc Pages
46+
47+
For each relevant commit, determine which doc page(s) it affects. Use this mapping as a starting point:
48+
49+
| Code area | Likely doc page(s) |
50+
|---|---|
51+
| `crates/openshell-cli/` (gateway commands) | `docs/sandboxes/manage-gateways.mdx` |
52+
| `crates/openshell-cli/` (sandbox commands) | `docs/sandboxes/manage-sandboxes.mdx` |
53+
| `crates/openshell-cli/` (provider commands) | `docs/sandboxes/manage-providers.mdx` |
54+
| `crates/openshell-cli/` (new top-level command) | May need a new page or `docs/reference/` entry |
55+
| Proxy or policy code | `docs/sandboxes/policies.mdx`, `docs/reference/policy-schema.mdx` |
56+
| Inference code | `docs/inference/configure.mdx` |
57+
| `python/` (SDK changes) | `docs/reference/` or `docs/get-started/quickstart.mdx` |
58+
| `proto/` (API changes) | `docs/reference/` |
59+
| `deploy/` (Dockerfile, Helm) | `docs/sandboxes/manage-gateways.mdx`, `docs/about/architecture.mdx` |
60+
| Community sandbox definitions | `docs/sandboxes/community-sandboxes.mdx` |
61+
62+
If a commit does not map to any existing page but introduces a user-visible concept, flag it as needing a new page.
63+
64+
## Step 3: Read the Commit Details
65+
66+
For each commit that needs a doc update, read the full diff to understand the change:
67+
68+
```bash
69+
git show <commit-hash> --stat
70+
git show <commit-hash>
71+
```
72+
73+
Extract:
74+
75+
- What changed (new flag, renamed command, changed default, new feature).
76+
- Why it changed (from the commit message body, linked issue, or PR description).
77+
- Any breaking changes or migration steps.
78+
79+
## Step 4: Read the Current Doc Page
80+
81+
Before editing, read the full target doc page to understand its current content and structure:
82+
83+
```bash
84+
# Read the file
85+
```
86+
87+
Identify where the new content should go. Follow the page's existing structure.
88+
89+
## Step 5: Draft the Update
90+
91+
Write the doc update following the rules in `docs/CONTRIBUTING.mdx`. Key reminders:
92+
93+
- **Active voice, present tense, second person.**
94+
- **No unnecessary bold.** Reserve bold for UI labels and parameter names.
95+
- **No em dashes** unless used sparingly. Prefer commas or separate sentences.
96+
- **Start sections with an introductory sentence** that orients the reader.
97+
- **No superlatives.** Say what the feature does, not how great it is.
98+
- **Code examples use `shell` language** for copyable commands, with no `$` prompt prefix.
99+
- **Use `text` fences** for transcripts, logs, or shell sessions that should not be copied verbatim.
100+
- **Include the SPDX header as YAML comments in frontmatter** if creating a new page.
101+
- **Match existing Fern frontmatter format** if creating a new page, including `sidebar-title`, `keywords`, and `position` when they are relevant. Use frontmatter `slug` only for folder-discovered pages or absolute URL overrides.
102+
- **Use `sidebar-title` for short nav labels**. For explicit navigation entries, keep relative `slug` values in `docs/index.yml` instead of page frontmatter.
103+
- **Keep explicit `page:` entries in `docs/index.yml`**. Fern still requires them. If the page defines `sidebar-title`, set `page:` to that value. Otherwise set `page:` to the page frontmatter `title`.
104+
- **Use `skip-slug: true` in `docs/index.yml`** when a child page should live at the parent section path.
105+
- **Use `keywords` as a comma-separated string**.
106+
- **Do not add a duplicate H1**. Fern renders the page title from frontmatter.
107+
- **Always write NVIDIA in all caps.** Wrong: Nvidia, nvidia.
108+
- **Always capitalize OpenShell correctly.** Wrong: openshell, Openshell, openShell.
109+
- **Do not number section titles.** Wrong: "Section 1: Deploy a Gateway" or "Step 3: Verify." Use plain descriptive titles.
110+
- **No colons in titles.** Wrong: "Gateways: Deploy and Manage." Write "Deploy and Manage Gateways" instead.
111+
- **Use colons only to introduce a list.** Do not use colons as general-purpose punctuation between clauses.
112+
113+
When updating an existing page:
114+
115+
- Add content in the logical place within the existing structure.
116+
- Do not reorganize sections unless the change requires it.
117+
- Update any cross-references or "Next Steps" links if relevant.
118+
119+
When creating a new page:
120+
121+
- Follow the frontmatter template from `docs/CONTRIBUTING.mdx`.
122+
- Add the page to the appropriate section in `docs/index.yml`.
123+
124+
## Step 6: Present the Results
125+
126+
After drafting all updates, present a summary to the user:
127+
128+
```
129+
## Doc Updates from Commits
130+
131+
### Updated pages
132+
- `docs/sandboxes/manage-gateways.mdx`: Added `--gpu` flag documentation (from commit abc1234).
133+
- `docs/reference/policy-schema.mdx`: Updated network policy schema for new `tls_inspect` field (from commit def5678).
134+
135+
### New pages needed
136+
- None (or list any new pages created).
137+
138+
### Commits with no doc impact
139+
- `chore(deps): bump tokio` (abc1234) — internal dependency, no user-facing change.
140+
- `test(e2e): add gateway timeout test` (def5678) — test-only change.
141+
```
142+
143+
## Step 7: Build and Verify
144+
145+
After making changes, validate the Fern docs locally:
146+
147+
```bash
148+
mise run docs
149+
```
150+
151+
If a human needs to inspect rendering while iterating, they can also run:
152+
153+
```bash
154+
mise run docs:serve
155+
```
156+
157+
Check for:
158+
159+
- Validation warnings or errors.
160+
- Broken cross-references.
161+
- Correct rendering of new content in the PR preview when available.
162+
163+
## Tips
164+
165+
- When in doubt about whether a commit needs a doc update, check if the commit message references a CLI flag, config option, or user-visible behavior.
166+
- Group related commits that touch the same doc page into a single update rather than making multiple small edits.
167+
- If a commit is a breaking change, add a note at the top of the relevant section using a Fern `<Warning>` callout.
168+
- PRs that are purely internal refactors with no behavior change do not need doc updates, even if they touch high-signal directories.
169+
170+
## Example Usage
171+
172+
User says: "Catch up the docs for everything merged since v0.2.0."
173+
174+
1. Run `git log v0.2.0..HEAD --oneline --no-merges --name-only`.
175+
2. Filter to `feat`, `fix`, `refactor`, `perf` commits touching user-facing code.
176+
3. Map each to a doc page.
177+
4. Read the commit diffs and current doc pages.
178+
5. Draft updates following the style guide.
179+
6. Present the summary.
180+
7. Run `mise run docs` to verify.

‎.github/copy-pr-bot.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
enabled: true
2+
auto_sync_draft: false
3+
auto_sync_ready: true

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

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
name: Branch Docs Preview
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- "docs/**"
7+
- "fern/**"
8+
- "mise.toml"
9+
- "tasks/docs.toml"
10+
- ".github/workflows/branch-docs.yml"
11+
- ".github/workflows/release-tag.yml"
12+
13+
permissions:
14+
contents: read
15+
pull-requests: write
16+
17+
jobs:
18+
preview:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout repository
22+
uses: actions/checkout@v4
23+
24+
- name: Check Fern preview availability
25+
id: fern-preview
26+
env:
27+
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
28+
run: |
29+
if [ -n "$FERN_TOKEN" ]; then
30+
echo "enabled=true" >> "$GITHUB_OUTPUT"
31+
else
32+
echo "enabled=false" >> "$GITHUB_OUTPUT"
33+
echo "::notice::Skipping Fern docs preview because FERN_TOKEN is unavailable. This is expected for fork PRs and repos without Fern preview credentials configured."
34+
fi
35+
36+
- name: Setup Node.js
37+
uses: actions/setup-node@v6
38+
with:
39+
node-version: "24"
40+
41+
- name: Install Fern CLI
42+
run: |
43+
FERN_VERSION=$(node -p "require('./fern/fern.config.json').version")
44+
npm install -g "fern-api@${FERN_VERSION}"
45+
46+
- name: Validate docs
47+
working-directory: ./fern
48+
run: fern check
49+
50+
- name: Generate preview URL
51+
if: ${{ steps.fern-preview.outputs.enabled == 'true' }}
52+
id: generate-docs
53+
env:
54+
FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
55+
PREVIEW_ID: pr-${{ github.event.pull_request.number }}
56+
working-directory: ./fern
57+
run: |
58+
OUTPUT=$(fern generate --docs --preview --id "$PREVIEW_ID" 2>&1)
59+
echo "$OUTPUT"
60+
URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()')
61+
if [ -z "$URL" ]; then
62+
echo "::error::Failed to generate preview URL. See fern output above."
63+
exit 1
64+
fi
65+
echo "preview_url=$URL" >> "$GITHUB_OUTPUT"
66+
67+
- name: Post or update PR comment
68+
if: ${{ steps.fern-preview.outputs.enabled == 'true' }}
69+
env:
70+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
71+
PR_NUMBER: ${{ github.event.pull_request.number }}
72+
PREVIEW_URL: ${{ steps.generate-docs.outputs.preview_url }}
73+
run: |
74+
BODY=":herb: **Preview your docs:** <${PREVIEW_URL}>"
75+
MARKER="<!-- preview-docs -->"
76+
BODY="${BODY}
77+
78+
${MARKER}"
79+
80+
COMMENT_ID=$(gh api "repos/${{ github.repository }}/issues/${PR_NUMBER}/comments" \
81+
--jq ".[] | select(.body | contains(\"${MARKER}\")) | .id" | head -1)
82+
83+
if [ -n "$COMMENT_ID" ]; then
84+
gh api "repos/${{ github.repository }}/issues/comments/${COMMENT_ID}" \
85+
-X PATCH -f body="$BODY"
86+
else
87+
gh api "repos/${{ github.repository }}/issues/${PR_NUMBER}/comments" \
88+
-f body="$BODY"
89+
fi

‎.github/workflows/e2e-gpu-test.yaml‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
name: GPU E2E Test
2+
3+
on:
4+
workflow_call:
5+
inputs:
6+
image-tag:
7+
description: "Image tag to test (typically the commit SHA)"
8+
required: true
9+
type: string
10+
11+
permissions:
12+
contents: read
13+
packages: read
14+
15+
jobs:
16+
e2e-gpu:
17+
name: "E2E GPU (${{ matrix.name }})"
18+
runs-on: ${{ matrix.runner }}
19+
continue-on-error: ${{ matrix.experimental }}
20+
timeout-minutes: 30
21+
strategy:
22+
fail-fast: false
23+
matrix:
24+
include:
25+
- name: linux-arm64
26+
runner: linux-arm64-gpu-l4-latest-1
27+
cluster: e2e-gpu-arm64
28+
port: "8083"
29+
experimental: false
30+
- name: linux-amd64
31+
runner: linux-amd64-gpu-rtxpro6000-latest-1
32+
cluster: e2e-gpu-amd64
33+
port: "8084"
34+
experimental: false
35+
- name: wsl-amd64
36+
runner: wsl-amd64-gpu-rtxpro6000-latest-1
37+
cluster: e2e-gpu-wsl
38+
port: "8085"
39+
experimental: true
40+
container:
41+
image: ghcr.io/nvidia/openshell/ci:latest
42+
credentials:
43+
username: ${{ github.actor }}
44+
password: ${{ secrets.GITHUB_TOKEN }}
45+
options: --privileged
46+
volumes:
47+
- /var/run/docker.sock:/var/run/docker.sock
48+
env:
49+
MISE_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
50+
IMAGE_TAG: ${{ inputs.image-tag }}
51+
OPENSHELL_REGISTRY: ghcr.io/nvidia/openshell
52+
OPENSHELL_REGISTRY_HOST: ghcr.io
53+
OPENSHELL_REGISTRY_NAMESPACE: nvidia/openshell
54+
OPENSHELL_REGISTRY_USERNAME: ${{ github.actor }}
55+
OPENSHELL_REGISTRY_PASSWORD: ${{ secrets.GITHUB_TOKEN }}
56+
OPENSHELL_GATEWAY: ${{ matrix.cluster }}
57+
steps:
58+
- uses: actions/checkout@v4
59+
60+
- name: Log in to GHCR
61+
run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
62+
63+
- name: Pull cluster image
64+
run: docker pull ghcr.io/nvidia/openshell/cluster:${{ inputs.image-tag }}
65+
66+
- name: Install Python dependencies and generate protobuf stubs
67+
run: uv sync --frozen && mise run --no-prepare python:proto
68+
69+
- name: Bootstrap GPU cluster
70+
env:
71+
GATEWAY_HOST: host.docker.internal
72+
GATEWAY_PORT: ${{ matrix.port }}
73+
CLUSTER_NAME: ${{ matrix.cluster }}
74+
# Passes --gpu to the gateway bootstrap so the cluster comes up with GPU passthrough enabled.
75+
CLUSTER_GPU: "1"
76+
SKIP_IMAGE_PUSH: "1"
77+
SKIP_CLUSTER_IMAGE_BUILD: "1"
78+
OPENSHELL_CLUSTER_IMAGE: ghcr.io/nvidia/openshell/cluster:${{ inputs.image-tag }}
79+
run: mise run --no-prepare --skip-deps cluster
80+
81+
- name: Run tests
82+
run: mise run --no-prepare --skip-deps e2e:python:gpu

0 commit comments

Comments
 (0)