Skip to content

MARKDOWN SOURCE

Raw
---
name: silen-infra
description: "Work in silen's infrastructure: Twig (self-hosted Git and pull requests), Ino (release and Once deployment), and Info (Infomaniak DNS for silenlocatelli.ch and hodis.ch)."
---

# silen infra

This is the working map of the self-hosted stack. Read the section for the task
you are doing, then follow the repository's own `AGENTS.md` and `mise.toml`
when they are stricter. The `any` CLI installs this file at
`.opencode/skills/silen-infra/SKILL.md`.

## The map

| Thing | Location | What it is |
| --- | --- | --- |
| Twig server | <https://twig.silenlocatelli.ch> | Self-hosted Git server with a web UI and pull requests |
| Twig source | `https://twig.silenlocatelli.ch/twig/twig` | Rust/Actix-web server; repo for Twig itself |
| Ino source | `https://twig.silenlocatelli.ch/twig/ino` | Zig CLI for versions, releases, and Once deployments |
| Info | `https://twig.silenlocatelli.ch/silen/info` | OpenTofu/Terraform config for Infomaniak DNS |
| Any | `https://twig.silenlocatelli.ch/silen/any` | Small CLI that installs this skill into a repo |
| Deployment proxy | `proxy.silenlocatelli.ch` | Once/Kamal proxy in front of deployed apps |
| Ino deployment server | `https://ino.silenlocatelli.ch` | Once-compatible server Ino releases deploy to |

Repository paths on Twig are `{namespace}/{repo}`, for example `silen/info` or
`twig/ino`. HTTPS clones accept an optional `.git` suffix:
`https://twig.silenlocatelli.ch/silen/info.git`.

## Preferred project setup

When starting a project or reshaping an existing one, default to this shape:

- **Server-rendered UI first.** If the project has a server, render HTML on the
  server and use **HTMX 4** for interaction. Add small vanilla JavaScript only
  for what HTMX cannot do cleanly.
- **Vendor every asset.** CSS, HTMX, fonts, and any JavaScript library are
  checked into the repository and served by the app itself. No CDNs, no remote
  imports, and no runtime downloads.
- **A self-served pure JavaScript frontend is acceptable** when the app is
  genuinely client-side. Serve the JS and CSS from the repository, and vendor
  only libraries that are sensible for the task.
- **No unused vendor code.** Vendor only the files and features actually used;
  remove dead JavaScript and unused library files. Do not ship a whole library
  for one helper.
- **Keep vendored code intact.** Keep each library's license file next to it and
  do not rewrite vendored sources; adapt your own code around them.
- **Degrade gracefully.** Prefer progressive enhancement: core reading and
  navigation should still work if JavaScript fails.

## Twig: branches, pull requests, CI

**Prefer committing directly to `main`.** Push small, reviewed changes straight
to `main` instead of opening a pull request. Use a pull request only when the
user asks for one, when the change is large or risky, or when review is
genuinely useful. Twig does not require a PR (there are no required status
checks), so a PR is a collaboration choice, not a gate. The workflow below is
for the cases where a PR is wanted.

### Authenticate once

Create a personal access token in Twig under **Settings → Access tokens**. Grant
`view_namespace` for reading and `push_changes` for pushing, opening pull
requests, reviewing, and merging. For the Forgejo-compatible CLI:

```sh
fj --host https://twig.silenlocatelli.ch auth add-token
```

Twig also accepts the token directly:

```sh
export TWIG_TOKEN=...   # never commit it
curl -fsS -H "Authorization: token $TWIG_TOKEN" \
  https://twig.silenlocatelli.ch/api/v1/me
```

Git writes use HTTP Basic Auth. Use your Twig username and password, or the token
as the password. A credential helper keeps it out of the remote URL.

### Commit and push

For a normal small change, work on `main`:

```sh
git switch main
git pull
# edit, test, then:
git add -A
git commit -m "feat: add a subdomain for books"
git push
```

When a pull request is actually needed, branch from `main`:

```sh
git switch -c t3/<slug>
```

Use `t3/<slug>` for work started from a T3 Code thread; `feat/<slug>`,
`fix/<slug>`, or `docs/<slug>` are fine too. Keep one topic per branch. Twig
pull requests can only merge a branch from the **same repository** — forks are
not supported.

### Commit style

Use conventional commits; Ino reads them to choose a version bump.

```text
feat: add a subdomain for books
fix: reject stale branch heads
perf: cache rendered markdown
docs: explain Once labels
refactor: split the release parser
test: cover duplicate pull requests
chore: bump the Zig toolchain
feat!: drop the old config key
```

`!` or a `BREAKING CHANGE:` footer marks a breaking change. `feat` and `perf`
bump the minor version; everything else defaults to a patch.

### If you open a pull request

Only do this when a PR is preferred or requested. Push the branch first, then
create the request against `main`:

```sh
git push -u origin t3/<slug>

fj --host https://twig.silenlocatelli.ch pr create \
  --base main \
  --head t3/<slug> \
  --title "feat: add books subdomain" \
  --body "Adds the CNAME and the deployment label.

Verified with: mise run validate"
```

`fj pr create -A` fills the title and body from the commits. `--web` opens the
web form instead. Add `-r owner/repo` when the remote does not identify the
repository. Without `fj`, use the Forgejo-compatible API:

```sh
curl -fsS -X POST \
  "https://twig.silenlocatelli.ch/api/v1/repos/silen/info/pulls" \
  -H "Authorization: token $TWIG_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
    --arg base main \
    --arg head t3/<slug> \
    --arg title 'feat: add books subdomain' \
    --arg body 'Adds the CNAME and the deployment label.' \
    '{base:$base, head:$head, title:$title, body:$body}')"
```

The response contains `number` and `html_url`. Open requests also appear in the
web UI under the repository's **Pull requests** tab. Every request has a
read-only ref `refs/pull/{number}/head`; do not push to `refs/pull/*`.

### Review and merge

```sh
fj --host https://twig.silenlocatelli.ch pr status <number> --wait
fj --host https://twig.silenlocatelli.ch pr view <number>
fj --host https://twig.silenlocatelli.ch pr checkout <number>
```

Approve or request changes through the review API (the `fj` build may only list
and request reviewers):

```sh
curl -fsS -X POST \
  "https://twig.silenlocatelli.ch/api/v1/repos/silen/info/pulls/<number>/reviews" \
  -H "Authorization: token $TWIG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event":"APPROVED","body":"Checks pass."}'
```

`event` is `APPROVED`, `REQUEST_CHANGES`, or `COMMENT`. Merge with one of Twig's
three styles:

```sh
fj --host https://twig.silenlocatelli.ch pr merge <number> \
  --method squash --delete
```

Twig also accepts `--method merge` and `--method rebase`. Updating a branch from
its base supports merge only; rebase updates are not offered.

### CI

A repository opts into Twig CI by committing `.twig/mise.toml`:

```toml
[tools]
rust = { version = "nightly-2026-10-31" }
"cargo-binstall" = "latest"
"cargo:cargo-nextest" = "latest"

[tasks.ci]
dir = ".."
run = ['cargo fmt --check', 'cargo clippy --all-targets', 'cargo nextest run']
```

Only `.twig/mise.toml` is used; a root `mise.toml` is not merged into a run.
Tasks execute from `.twig/` unless `dir = ".."`. A push queues one run per moved
branch; pull requests show the head commit's combined `ci` status. Statuses are
reported but **do not gate a merge**, so a green check is a convention, not a
server guarantee. CI must be enabled by the server operator (`TWIG_CI=1`) and
runs with the server user's filesystem access — treat it as trusted code.

Read runs and logs with `fj actions tasks` or
`GET /api/v1/repos/{owner}/{repo}/actions/tasks`. Dispatch manually with
`fj actions dispatch ci <branch>`.

### Twig repository config

`.twig.toml` at the repository root controls visibility and views:

```toml
private = true
deleteable = false
ignore_for_view = [".opencode/", "AGENTS.md", "docs/plans/"]

[scripts.install]
name = "Install"
scripts = [
  { name = "Install CLI", path = "scripts/install.sh", shell = "bash" },
]
```

`private = true` requires authentication even for reads. `deleteable = true` is
required before the UI/API can delete the repository. Keep secrets out of this
file and out of the repository.

### Twig limits worth remembering

- Pull requests are same-repository only; no forks.
- No labels, milestones, issues, projects, or thread resolution.
- No required status checks.
- No rebase updates for pull requests.
- Creating a private repository through the API is not supported; set
  `private = true` in `.twig.toml`.
- Content writes are limited to 1 MiB; Git pushes and binary uploads to 512 MiB.
- API reads always require a token, even for public repositories.

## Ino: release and deploy

Ino is the Zig CLI that versions a project, pushes a Docker image, and asks the
Ino server to deploy it through Once.

### Install

```sh
git clone https://twig.silenlocatelli.ch/twig/ino
cd ino
mise run install          # installs to ~/.local/bin, or $INO_PREFIX/bin
```

The install task removes a stale cargo-installed `ino` instead of shadowing it.

### Release

```sh
ino          # same as `ino auto`: pick the bump from conventional commits
ino patch
ino minor
ino major
```

The release flow:

1. Reads the current version from `build.zig.zon` `.version` (preferred) or
   `Cargo.toml` `[package].version`; if both exist, Zig wins.
2. Picks a bump: breaking → major, `feat`/`perf` → minor, else patch.
3. Updates `Cargo.toml` and the workspace `Cargo.lock` for Rust (the lockfile is
   intentionally left out of the release commit), or `build.zig.zon` for Zig.
4. If a root `Dockerfile` exists, builds and pushes the versioned image and
   `latest` with Docker Buildx. The Dockerfile must declare
   `LABEL remote="owner/image"` and the registry login must already exist.
5. Commits and pushes the release. The branch needs a usable Git remote.
6. If both deployment labels are present, calls the Ino server and waits for the
   app to report the requested image as running.

Use `ino new` to print all derived versions, and `ino exec <command...>` to run a
command with version environment variables injected (`INO_*` and `VERSION_*`).

### Container contract for a deployable app

The image must:

- Serve HTTP on `0.0.0.0:80`.
- Return a successful unauthenticated `GET /up`.
- Persist durable data under `/storage` (configure the app's real database and
  upload paths to use it).
- Run the server as the foreground process (PID 1 behaviour), not a detached
  background process.

Add both labels to the root `Dockerfile`; they must appear together:

```dockerfile
LABEL remote="silenloc/myapp" \
      ino.deploy.server="https://ino.silenlocatelli.ch" \
      ino.deploy.host="myapp.silenlocatelli.ch"
```

- `remote` is the actual registry repository.
- `ino.deploy.server` is the Ino server origin.
- `ino.deploy.host` is the public hostname. It must have a DNS record in the
  Info repo (normally a CNAME to `proxy.silenlocatelli.ch`).
- Never put `INO_API_KEY`, registry passwords, or app secrets in labels.

The local release environment needs Docker Buildx, registry authentication,
Git push access, and a non-empty `INO_API_KEY`. The key is read from the local
environment only; it is not baked into the image.

### First deployment and day-two operations

For a brand-new app, release and create it with:

```sh
ino once remote create
```

For an app that already exists on the server, the normal `ino` release updates
it. Other Once operations:

```sh
ino once list
ino once deploy ghcr.io/owner/app:latest --host app.silenlocatelli.ch
ino once start app.silenlocatelli.ch
ino once stop app.silenlocatelli.ch
ino once exec app.silenlocatelli.ch sh
ino once update app.silenlocatelli.ch --image ghcr.io/owner/app:v2
ino once backup app.silenlocatelli.ch ./app-backup.tar.gz
ino once restore ./app-backup.tar.gz
ino once remove app.silenlocatelli.ch          # keeps the data volume
ino once remove app.silenlocatelli.ch --remove-data
ino once keys reset app.silenlocatelli.ch --secret-key-base
```

Use `--registry-password-stdin` rather than putting a registry password in
shell history. `ino once` drives the local Docker daemon; it does not need the
upstream `once` executable.

### Deployment checks

Before calling a deployment done:

```sh
curl -fsS https://<host>/up
curl -fsS https://<host>/
```

Confirm the image tag the server reports matches the released version, and that
data written before a redeploy survives. A successful image build is not a
deployment.

## Info: DNS and subdomains

Info is an OpenTofu configuration for the Infomaniak DNS zones
`silenlocatelli.ch` and `hodis.ch`. The provider is `Infomaniak/infomaniak`
`~> 1.4.1`; the toolchain is `opentofu 1.13.0`.

```sh
git clone https://twig.silenlocatelli.ch/silen/info
cd info
mise install
mise run init
mise run plan
mise run apply          # runs plan first
mise run fmt
mise run validate
```

`infomaniak_token` is a sensitive variable. Provide it through
`TF_VAR_infomaniak_token` or a local untracked file, and never commit a token.
Do not edit `infomaniak_api_*.json` by hand — it is a downloaded snapshot, not
the source of truth.

### Add a subdomain

Append a record to `records-silenlocatelli.tf` (or `records-hodis.tf` for
`hodis.ch`). New app subdomains normally point at the Once proxy:

```hcl
resource "infomaniak_record" "silenlocatelli_myapp_cname" {
  zone_fqdn = infomaniak_zone.silenlocatelli.fqdn
  source    = "myapp"
  type      = "CNAME"
  ttl       = 3600
  target    = "proxy.silenlocatelli.ch"
}
```

Then:

```sh
mise run fmt
mise run plan     # inspect the add
mise run apply
dig +short myapp.silenlocatelli.ch
```

Naming and address facts:

- `source` is relative to the zone: `myapp`, not `myapp.silenlocatelli.ch`.
- `silenlocatelli.ch` app subdomains normally CNAME to
  `proxy.silenlocatelli.ch`.
- `proxy.silenlocatelli.ch` resolves to `83.228.212.88` (A) and
  `2001:1600:18:102::17e` (AAAA).
- The `silenlocatelli.ch` apex is managed by Infomaniak nameservers and carries
  mail/SPF/DMARC records; do not repoint it casually.
- `hodis.ch` currently has apex A/AAAA records pointing directly at the proxy.
- `fig.silenlocatelli.ch` has its own A/AAAA records, and `auth` points at
  Auth0. Treat existing non-proxy records as intentional.
- Add an `import` block only when adopting a record that already exists in
  Infomaniak; a newly created record needs none.

## Code quality before committing

Run the repository's own task first. It is the contract:

```sh
mise run verify
```

Then check the language-specific baseline below. A change that skips the repo's
formatter, linter, or tests is not ready to push.

### Rust

The Rust projects (Twig, Tree, Personal Page) pin a toolchain and use the same
verify shape:

```sh
cargo fmt --check
cargo clippy --all-targets
cargo nextest run
```

- Keep the pinned `rust-toolchain.toml` channel; bump it deliberately in its own
  commit.
- Treat Clippy warnings as defects. Fix the code; do not add a blanket
  `#[allow(...)]`.
- Use `Result` and `?` for fallible paths. Keep `unwrap`/`expect` out of request
  handlers and startup paths; tests may use them.
- Prefer clear ownership and borrowing over cloning to silence the borrow
  checker.
- Keep `Cargo.lock` committed for binary projects.
- Twig-specific: do not eagerly connect to the SQLite file; follow the existing
  lazy connection pattern.
- Run tests that touch HTTP, Git, or database code against the real
  `mise run verify` task, not only `cargo check`.

### Zig

The Zig projects (Ino, Any) use:

```sh
zig fmt --check build.zig src
zig build test
zig build -Doptimize=ReleaseSafe
```

- Use only the Zig standard library unless the project already vendored an
  approved dependency; do not add packages casually.
- Let the test allocator catch leaks. Free or arena-allocate every allocation,
  and use `errdefer`/`defer` on error paths.
- Return errors for bad input; do not use `catch unreachable` or `unreachable`
  on user-controlled data.
- Keep `@embedFile` payloads and build options declared in `build.zig` so tests
  compile with the same inputs.
- Tests live beside the code in `test` blocks, and pure parsing/composition
  logic is preferred over tests that depend on the process cwd.
- Formatting is `zig fmt`; do not hand-align code against it.

### JavaScript

The web assets in Twig are deliberately dependency-free browser JavaScript: no
bundler, no npm build step, and vendored libraries are left untouched.

- Put new browser code in its own file under `assets/` and wrap it in an IIFE
  with `"use strict"`; do not leak globals.
- Match the surrounding style (`var`/`function` in older files, semicolons,
  the file's indentation). Do not reformat a whole file for a small change.
- Guard browser APIs that can throw or be unavailable, especially
  `localStorage` and `sessionStorage`, with `try`/`catch`.
- Use `textContent` for untrusted text and sanitize rendered HTML; Twig vendors
  DOMPurify for this. Never interpolate untrusted values into `innerHTML`.
- Use event delegation for repeated controls and clean up listeners with the
  element's lifecycle.
- Handle rejected promises; do not leave a floating async call without a
  `catch`.
- If a repository does have `package.json`, run its own formatter, linter,
  typecheck, and tests (`mise run verify` first), and ask before adding a
  dependency.
- Use **Bun**, not Node, for JavaScript tooling: `bun install`, `bun run`, and
  `bun test`. Do not use `node` or `npm` to run or check project code.
- With no tooling, at minimum run `bun build --no-bundle <file>` for syntax and
  exercise the page in a browser.

### Universal change hygiene

- Keep the diff focused; split unrelated refactors into their own commit or PR.
- Update docs, `.twig.toml`, `mise.toml`, and deployment labels when behaviour
  changes.
- Do not commit `.env`, tokens, registry passwords, DNS credentials, or build
  outputs.
- Re-read `git diff` before pushing, and say what was verified in the commit
  message or PR description.
- If a check cannot run, say so explicitly instead of claiming success.

name: silen-infra description: "Work in silen's infrastructure: Twig (self-hosted Git and pull requests), Ino (release and Once deployment), and Info (Infomaniak DNS for silenlocatelli.ch and hodis.ch)."

silen infra

This is the working map of the self-hosted stack. Read the section for the task you are doing, then follow the repository's own AGENTS.md and mise.toml when they are stricter. The any CLI installs this file at .opencode/skills/silen-infra/SKILL.md.

The map

ThingLocationWhat it is
Twig serverhttps://twig.silenlocatelli.chSelf-hosted Git server with a web UI and pull requests
Twig sourcehttps://twig.silenlocatelli.ch/twig/twigRust/Actix-web server; repo for Twig itself
Ino sourcehttps://twig.silenlocatelli.ch/twig/inoZig CLI for versions, releases, and Once deployments
Infohttps://twig.silenlocatelli.ch/silen/infoOpenTofu/Terraform config for Infomaniak DNS
Anyhttps://twig.silenlocatelli.ch/silen/anySmall CLI that installs this skill into a repo
Deployment proxyproxy.silenlocatelli.chOnce/Kamal proxy in front of deployed apps
Ino deployment serverhttps://ino.silenlocatelli.chOnce-compatible server Ino releases deploy to

Repository paths on Twig are {namespace}/{repo}, for example silen/info or twig/ino. HTTPS clones accept an optional .git suffix: https://twig.silenlocatelli.ch/silen/info.git.

Preferred project setup

When starting a project or reshaping an existing one, default to this shape:

  • Server-rendered UI first. If the project has a server, render HTML on the server and use HTMX 4 for interaction. Add small vanilla JavaScript only for what HTMX cannot do cleanly.
  • Vendor every asset. CSS, HTMX, fonts, and any JavaScript library are checked into the repository and served by the app itself. No CDNs, no remote imports, and no runtime downloads.
  • A self-served pure JavaScript frontend is acceptable when the app is genuinely client-side. Serve the JS and CSS from the repository, and vendor only libraries that are sensible for the task.
  • No unused vendor code. Vendor only the files and features actually used; remove dead JavaScript and unused library files. Do not ship a whole library for one helper.
  • Keep vendored code intact. Keep each library's license file next to it and do not rewrite vendored sources; adapt your own code around them.
  • Degrade gracefully. Prefer progressive enhancement: core reading and navigation should still work if JavaScript fails.

Twig: branches, pull requests, CI

Prefer committing directly to main. Push small, reviewed changes straight to main instead of opening a pull request. Use a pull request only when the user asks for one, when the change is large or risky, or when review is genuinely useful. Twig does not require a PR (there are no required status checks), so a PR is a collaboration choice, not a gate. The workflow below is for the cases where a PR is wanted.

Authenticate once

Create a personal access token in Twig under Settings → Access tokens. Grant view_namespace for reading and push_changes for pushing, opening pull requests, reviewing, and merging. For the Forgejo-compatible CLI:

fj --host https://twig.silenlocatelli.ch auth add-token

Twig also accepts the token directly:

export TWIG_TOKEN=...   # never commit it
curl -fsS -H "Authorization: token $TWIG_TOKEN" \
  https://twig.silenlocatelli.ch/api/v1/me

Git writes use HTTP Basic Auth. Use your Twig username and password, or the token as the password. A credential helper keeps it out of the remote URL.

Commit and push

For a normal small change, work on main:

git switch main
git pull
# edit, test, then:
git add -A
git commit -m "feat: add a subdomain for books"
git push

When a pull request is actually needed, branch from main:

git switch -c t3/<slug>

Use t3/<slug> for work started from a T3 Code thread; feat/<slug>, fix/<slug>, or docs/<slug> are fine too. Keep one topic per branch. Twig pull requests can only merge a branch from the same repository — forks are not supported.

Commit style

Use conventional commits; Ino reads them to choose a version bump.

feat: add a subdomain for books
fix: reject stale branch heads
perf: cache rendered markdown
docs: explain Once labels
refactor: split the release parser
test: cover duplicate pull requests
chore: bump the Zig toolchain
feat!: drop the old config key

! or a BREAKING CHANGE: footer marks a breaking change. feat and perf bump the minor version; everything else defaults to a patch.

If you open a pull request

Only do this when a PR is preferred or requested. Push the branch first, then create the request against main:

git push -u origin t3/<slug>

fj --host https://twig.silenlocatelli.ch pr create \
  --base main \
  --head t3/<slug> \
  --title "feat: add books subdomain" \
  --body "Adds the CNAME and the deployment label.

Verified with: mise run validate"

fj pr create -A fills the title and body from the commits. --web opens the web form instead. Add -r owner/repo when the remote does not identify the repository. Without fj, use the Forgejo-compatible API:

curl -fsS -X POST \
  "https://twig.silenlocatelli.ch/api/v1/repos/silen/info/pulls" \
  -H "Authorization: token $TWIG_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
    --arg base main \
    --arg head t3/<slug> \
    --arg title 'feat: add books subdomain' \
    --arg body 'Adds the CNAME and the deployment label.' \
    '{base:$base, head:$head, title:$title, body:$body}')"

The response contains number and html_url. Open requests also appear in the web UI under the repository's Pull requests tab. Every request has a read-only ref refs/pull/{number}/head; do not push to refs/pull/*.

Review and merge

fj --host https://twig.silenlocatelli.ch pr status <number> --wait
fj --host https://twig.silenlocatelli.ch pr view <number>
fj --host https://twig.silenlocatelli.ch pr checkout <number>

Approve or request changes through the review API (the fj build may only list and request reviewers):

curl -fsS -X POST \
  "https://twig.silenlocatelli.ch/api/v1/repos/silen/info/pulls/<number>/reviews" \
  -H "Authorization: token $TWIG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event":"APPROVED","body":"Checks pass."}'

event is APPROVED, REQUEST_CHANGES, or COMMENT. Merge with one of Twig's three styles:

fj --host https://twig.silenlocatelli.ch pr merge <number> \
  --method squash --delete

Twig also accepts --method merge and --method rebase. Updating a branch from its base supports merge only; rebase updates are not offered.

CI

A repository opts into Twig CI by committing .twig/mise.toml:

[tools]
rust = { version = "nightly-2026-10-31" }
"cargo-binstall" = "latest"
"cargo:cargo-nextest" = "latest"

[tasks.ci]
dir = ".."
run = ['cargo fmt --check', 'cargo clippy --all-targets', 'cargo nextest run']

Only .twig/mise.toml is used; a root mise.toml is not merged into a run. Tasks execute from .twig/ unless dir = "..". A push queues one run per moved branch; pull requests show the head commit's combined ci status. Statuses are reported but do not gate a merge, so a green check is a convention, not a server guarantee. CI must be enabled by the server operator (TWIG_CI=1) and runs with the server user's filesystem access — treat it as trusted code.

Read runs and logs with fj actions tasks or GET /api/v1/repos/{owner}/{repo}/actions/tasks. Dispatch manually with fj actions dispatch ci <branch>.

Twig repository config

.twig.toml at the repository root controls visibility and views:

private = true
deleteable = false
ignore_for_view = [".opencode/", "AGENTS.md", "docs/plans/"]

[scripts.install]
name = "Install"
scripts = [
  { name = "Install CLI", path = "scripts/install.sh", shell = "bash" },
]

private = true requires authentication even for reads. deleteable = true is required before the UI/API can delete the repository. Keep secrets out of this file and out of the repository.

Twig limits worth remembering

  • Pull requests are same-repository only; no forks.
  • No labels, milestones, issues, projects, or thread resolution.
  • No required status checks.
  • No rebase updates for pull requests.
  • Creating a private repository through the API is not supported; set private = true in .twig.toml.
  • Content writes are limited to 1 MiB; Git pushes and binary uploads to 512 MiB.
  • API reads always require a token, even for public repositories.

Ino: release and deploy

Ino is the Zig CLI that versions a project, pushes a Docker image, and asks the Ino server to deploy it through Once.

Install

git clone https://twig.silenlocatelli.ch/twig/ino
cd ino
mise run install          # installs to ~/.local/bin, or $INO_PREFIX/bin

The install task removes a stale cargo-installed ino instead of shadowing it.

Release

ino          # same as `ino auto`: pick the bump from conventional commits
ino patch
ino minor
ino major

The release flow:

  1. Reads the current version from build.zig.zon .version (preferred) or Cargo.toml [package].version; if both exist, Zig wins.
  2. Picks a bump: breaking → major, feat/perf → minor, else patch.
  3. Updates Cargo.toml and the workspace Cargo.lock for Rust (the lockfile is intentionally left out of the release commit), or build.zig.zon for Zig.
  4. If a root Dockerfile exists, builds and pushes the versioned image and latest with Docker Buildx. The Dockerfile must declare LABEL remote="owner/image" and the registry login must already exist.
  5. Commits and pushes the release. The branch needs a usable Git remote.
  6. If both deployment labels are present, calls the Ino server and waits for the app to report the requested image as running.

Use ino new to print all derived versions, and ino exec <command...> to run a command with version environment variables injected (INO_* and VERSION_*).

Container contract for a deployable app

The image must:

  • Serve HTTP on 0.0.0.0:80.
  • Return a successful unauthenticated GET /up.
  • Persist durable data under /storage (configure the app's real database and upload paths to use it).
  • Run the server as the foreground process (PID 1 behaviour), not a detached background process.

Add both labels to the root Dockerfile; they must appear together:

LABEL remote="silenloc/myapp" \
      ino.deploy.server="https://ino.silenlocatelli.ch" \
      ino.deploy.host="myapp.silenlocatelli.ch"
  • remote is the actual registry repository.
  • ino.deploy.server is the Ino server origin.
  • ino.deploy.host is the public hostname. It must have a DNS record in the Info repo (normally a CNAME to proxy.silenlocatelli.ch).
  • Never put INO_API_KEY, registry passwords, or app secrets in labels.

The local release environment needs Docker Buildx, registry authentication, Git push access, and a non-empty INO_API_KEY. The key is read from the local environment only; it is not baked into the image.

First deployment and day-two operations

For a brand-new app, release and create it with:

ino once remote create

For an app that already exists on the server, the normal ino release updates it. Other Once operations:

ino once list
ino once deploy ghcr.io/owner/app:latest --host app.silenlocatelli.ch
ino once start app.silenlocatelli.ch
ino once stop app.silenlocatelli.ch
ino once exec app.silenlocatelli.ch sh
ino once update app.silenlocatelli.ch --image ghcr.io/owner/app:v2
ino once backup app.silenlocatelli.ch ./app-backup.tar.gz
ino once restore ./app-backup.tar.gz
ino once remove app.silenlocatelli.ch          # keeps the data volume
ino once remove app.silenlocatelli.ch --remove-data
ino once keys reset app.silenlocatelli.ch --secret-key-base

Use --registry-password-stdin rather than putting a registry password in shell history. ino once drives the local Docker daemon; it does not need the upstream once executable.

Deployment checks

Before calling a deployment done:

curl -fsS https://<host>/up
curl -fsS https://<host>/

Confirm the image tag the server reports matches the released version, and that data written before a redeploy survives. A successful image build is not a deployment.

Info: DNS and subdomains

Info is an OpenTofu configuration for the Infomaniak DNS zones silenlocatelli.ch and hodis.ch. The provider is Infomaniak/infomaniak ~> 1.4.1; the toolchain is opentofu 1.13.0.

git clone https://twig.silenlocatelli.ch/silen/info
cd info
mise install
mise run init
mise run plan
mise run apply          # runs plan first
mise run fmt
mise run validate

infomaniak_token is a sensitive variable. Provide it through TF_VAR_infomaniak_token or a local untracked file, and never commit a token. Do not edit infomaniak_api_*.json by hand — it is a downloaded snapshot, not the source of truth.

Add a subdomain

Append a record to records-silenlocatelli.tf (or records-hodis.tf for hodis.ch). New app subdomains normally point at the Once proxy:

resource "infomaniak_record" "silenlocatelli_myapp_cname" {
  zone_fqdn = infomaniak_zone.silenlocatelli.fqdn
  source    = "myapp"
  type      = "CNAME"
  ttl       = 3600
  target    = "proxy.silenlocatelli.ch"
}

Then:

mise run fmt
mise run plan     # inspect the add
mise run apply
dig +short myapp.silenlocatelli.ch

Naming and address facts:

  • source is relative to the zone: myapp, not myapp.silenlocatelli.ch.
  • silenlocatelli.ch app subdomains normally CNAME to proxy.silenlocatelli.ch.
  • proxy.silenlocatelli.ch resolves to 83.228.212.88 (A) and 2001:1600:18:102::17e (AAAA).
  • The silenlocatelli.ch apex is managed by Infomaniak nameservers and carries mail/SPF/DMARC records; do not repoint it casually.
  • hodis.ch currently has apex A/AAAA records pointing directly at the proxy.
  • fig.silenlocatelli.ch has its own A/AAAA records, and auth points at Auth0. Treat existing non-proxy records as intentional.
  • Add an import block only when adopting a record that already exists in Infomaniak; a newly created record needs none.

Code quality before committing

Run the repository's own task first. It is the contract:

mise run verify

Then check the language-specific baseline below. A change that skips the repo's formatter, linter, or tests is not ready to push.

Rust

The Rust projects (Twig, Tree, Personal Page) pin a toolchain and use the same verify shape:

cargo fmt --check
cargo clippy --all-targets
cargo nextest run
  • Keep the pinned rust-toolchain.toml channel; bump it deliberately in its own commit.
  • Treat Clippy warnings as defects. Fix the code; do not add a blanket #[allow(...)].
  • Use Result and ? for fallible paths. Keep unwrap/expect out of request handlers and startup paths; tests may use them.
  • Prefer clear ownership and borrowing over cloning to silence the borrow checker.
  • Keep Cargo.lock committed for binary projects.
  • Twig-specific: do not eagerly connect to the SQLite file; follow the existing lazy connection pattern.
  • Run tests that touch HTTP, Git, or database code against the real mise run verify task, not only cargo check.

Zig

The Zig projects (Ino, Any) use:

zig fmt --check build.zig src
zig build test
zig build -Doptimize=ReleaseSafe
  • Use only the Zig standard library unless the project already vendored an approved dependency; do not add packages casually.
  • Let the test allocator catch leaks. Free or arena-allocate every allocation, and use errdefer/defer on error paths.
  • Return errors for bad input; do not use catch unreachable or unreachable on user-controlled data.
  • Keep @embedFile payloads and build options declared in build.zig so tests compile with the same inputs.
  • Tests live beside the code in test blocks, and pure parsing/composition logic is preferred over tests that depend on the process cwd.
  • Formatting is zig fmt; do not hand-align code against it.

JavaScript

The web assets in Twig are deliberately dependency-free browser JavaScript: no bundler, no npm build step, and vendored libraries are left untouched.

  • Put new browser code in its own file under assets/ and wrap it in an IIFE with "use strict"; do not leak globals.
  • Match the surrounding style (var/function in older files, semicolons, the file's indentation). Do not reformat a whole file for a small change.
  • Guard browser APIs that can throw or be unavailable, especially localStorage and sessionStorage, with try/catch.
  • Use textContent for untrusted text and sanitize rendered HTML; Twig vendors DOMPurify for this. Never interpolate untrusted values into innerHTML.
  • Use event delegation for repeated controls and clean up listeners with the element's lifecycle.
  • Handle rejected promises; do not leave a floating async call without a catch.
  • If a repository does have package.json, run its own formatter, linter, typecheck, and tests (mise run verify first), and ask before adding a dependency.
  • Use Bun, not Node, for JavaScript tooling: bun install, bun run, and bun test. Do not use node or npm to run or check project code.
  • With no tooling, at minimum run bun build --no-bundle <file> for syntax and exercise the page in a browser.

Universal change hygiene

  • Keep the diff focused; split unrelated refactors into their own commit or PR.
  • Update docs, .twig.toml, mise.toml, and deployment labels when behaviour changes.
  • Do not commit .env, tokens, registry passwords, DNS credentials, or build outputs.
  • Re-read git diff before pushing, and say what was verified in the commit message or PR description.
  • If a check cannot run, say so explicitly instead of claiming success.