sylo-ignition 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yeti-Trix <131923258+Yeti-Trix@users.noreply.github.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# sylo-ignition
+
+Ignition 8.3 gateway + project assistant for Sylo. Lets the agent create and
+edit Ignition projects the way Ignition 8.3 is designed to be edited: **files on
+disk + REST scan** — no Designer automation, no zip import/export.
+
+- **Workflow**: `ignition_status` → `ignition_project_resources` →
+  `ignition_resource_read` → edit → `ignition_validate` →
+  `ignition_resource_write` → `ignition_scan` → `ignition_screenshot` →
+  `analyze_image` (vision design loop).
+- **8.3 only**: 8.1 keeps everything in an internal SQLite DB and has no REST
+  API — 8.1 support would be a separate, zip-based kit (deferred).
+- **Safety**: all mutating tools enforce the operator-managed
+  `assets/write-allowlist.json` (the agent must never edit it). Gateway
+  backups via `ignition_backup`. Forbidden targets (digest, `.bin`,
+  `.resources/`, runtime state) are refused in code.
+- **Connection config** lives outside git at `~/.ignition-sylo/config.json`
+  (`gateway_url`, `api_token`, `data_dir`, `default_project`). Setup recipe in
+  the `ignition` skill.
+- **Docs**: `references/` holds the offline 8.3 User Manual (1,566 pages,
+  Markdown), SDK guide, verified REST route map, and the fetch tool
+  (`scripts/fetch_docs.py`). 8.1 PDF bundle is git-ignored, re-fetchable.
+
+See `features_tracker/active/2026-08-30_16-59-56_sylo_ignition_package.md`
+for the design record.

package/assets/write-allowlist.json

@@ -0,0 +1,19 @@
+{
+  "allow_writes": true,
+  "allow_scan": true,
+  "allow_project_create": true,
+  "projects": [
+    {
+      "name": "SyloSandbox",
+      "enabled": true,
+      "label": "Agent scratch project — safe to experiment"
+    },
+    {
+      "name": "Example",
+      "enabled": false,
+      "label": "Ignition demo project — read-only by default"
+    }
+  ],
+  "updated_at": "2026-08-30T22:00:00Z",
+  "notes": "Operator-managed. sylo-ignition mutating tools enforce this file in Python — the agent cannot edit it. Add a project here to let the agent write its files; keep production projects out unless you want that. allow_scan gates POST /data/api/v1/scan/* (hot-apply of disk edits; scans ALL projects). allow_project_create gates creating NEW projects (isolated, low-risk)."
+}

package/extensions/index.ts

@@ -0,0 +1,349 @@
+/**
+ * sylo-ignition — Ignition 8.3 gateway + project assistant.
+ *
+ * File-based workflow on a live 8.3 gateway: author/edit project resources on
+ * disk (data/projects/**), trigger REST scans to hot-apply, screenshot Perspective
+ * sessions for vision verification. Writes are gated by the operator-managed
+ * write-allowlist (assets/write-allowlist.json) — enforced in Python, never
+ * agent-editable.
+ *
+ * @see features_tracker/active/2026-08-30_16-59-56_sylo_ignition_package.md
+ */
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import os from 'node:os'
+import fs from 'node:fs'
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { Type } from 'typebox'
+
+const execFileAsync = promisify(execFile)
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const SCRIPTS_DIR = path.join(PACKAGE_ROOT, 'scripts')
+
+type ToolContentBlock = { type: 'text'; text: string }
+
+const TIMEOUTS: Record<string, number> = {
+  'screenshot.py': 120_000,
+  'backup.py': 360_000,
+  'scan.py': 120_000,
+}
+
+function resolvePython(): { command: string; prefixArgs: string[] } {
+  const envPython = process.env.SYLO_PYTHON?.trim()
+  if (envPython) return { command: envPython, prefixArgs: [] }
+  return { command: process.platform === 'win32' ? 'python' : 'python3', prefixArgs: [] }
+}
+
+function toolError(text: string): { content: ToolContentBlock[] } {
+  return { content: [{ type: 'text', text }] }
+}
+
+function parseTrailingJson(stdout: string): Record<string, unknown> | null {
+  const trimmed = stdout.trim()
+  if (!trimmed) return null
+  try {
+    return JSON.parse(trimmed) as Record<string, unknown>
+  } catch {
+    /* fall through */
+  }
+  let idx = trimmed.lastIndexOf('\n{')
+  while (idx >= 0) {
+    const candidate = trimmed.slice(idx + 1)
+    try {
+      return JSON.parse(candidate) as Record<string, unknown>
+    } catch {
+      idx = trimmed.lastIndexOf('\n{', idx - 1)
+    }
+  }
+  return null
+}
+
+function tail(text: string, lines = 12): string {
+  return text.trim().split('\n').slice(-lines).join('\n').trim()
+}
+
+async function runPythonScript(
+  scriptName: string,
+  args: string[],
+  timeoutMs?: number,
+): Promise<{ content: ToolContentBlock[] }> {
+  const timeout = timeoutMs ?? TIMEOUTS[scriptName] ?? 90_000
+  const scriptPath = path.join(SCRIPTS_DIR, scriptName)
+  const { command, prefixArgs } = resolvePython()
+  try {
+    const { stdout, stderr } = await execFileAsync(command, [...prefixArgs, scriptPath, ...args], {
+      cwd: PACKAGE_ROOT,
+      maxBuffer: 64 * 1024 * 1024,
+      windowsHide: true,
+      timeout,
+      env: { ...process.env, PYTHONIOENCODING: 'utf-8', PYTHONUTF8: '1' },
+    })
+    const parsed = parseTrailingJson(stdout) as
+      | { ok?: boolean; error?: string; operator_chat?: string }
+      | null
+    if (!parsed) {
+      return toolError(tail(stdout) || stderr.trim() || `${scriptName} produced no output`)
+    }
+    if (parsed.ok === false) {
+      return toolError(String(parsed.error ?? `${scriptName} failed`))
+    }
+    if (typeof parsed.operator_chat === 'string' && parsed.operator_chat.trim()) {
+      return { content: [{ type: 'text', text: parsed.operator_chat.trim() }] }
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(parsed, null, 2) }] }
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException & { stdout?: string; stderr?: string }
+    const parsed = typeof e.stdout === 'string' ? parseTrailingJson(e.stdout) : null
+    if (parsed && typeof parsed.error === 'string' && parsed.error.trim()) {
+      return toolError(parsed.error.trim())
+    }
+    const detail = [
+      typeof e.stdout === 'string' ? tail(e.stdout) : '',
+      typeof e.stderr === 'string' ? tail(e.stderr) : '',
+    ]
+      .filter(Boolean)
+      .join('\n')
+    const message = err instanceof Error ? err.message : String(err)
+    return toolError(detail ? `${message}\n${detail}` : message)
+  }
+}
+
+/** Large content (view JSON) can exceed Windows argv limits — stage to a temp file. */
+async function stageContent(content: string): Promise<string[]> {
+  if (content.length < 6000) return ['--content', content]
+  const tmp = path.join(os.tmpdir(), `sylo-ignition-content-${Date.now()}.txt`)
+  await fs.promises.writeFile(tmp, content, 'utf-8')
+  return ['--content-file', tmp]
+}
+
+export default function piSyloIgnitionExtension(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: 'ignition_status',
+    label: 'Ignition gateway status',
+    description:
+      'Gateway reachability + version, project list, open Designer sessions (write-conflict warning), config presence, allowlist summary. Run this FIRST in any Ignition task.',
+    parameters: Type.Object({}),
+    async execute() {
+      return runPythonScript('status.py', [])
+    },
+  })
+
+  pi.registerTool({
+    name: 'ignition_project_resources',
+    label: 'Ignition project resource tree',
+    description:
+      'List a project\'s resources on disk (views, scripts, themes, etc.) grouped by module scope, with payload types. Read any of them with ignition_resource_read.',
+    parameters: Type.Object({
+      project: Type.Optional(Type.String({ description: 'Project name (default from config)' })),
+      filter: Type.Optional(Type.String({ description: 'Case-insensitive path substring filter' })),
+      files: Type.Optional(Type.Boolean({ description: 'Also list non-resource file groups' })),
+    }),
+    async execute(_id, params) {
+      const args: string[] = []
+      const project = String(params.project ?? '').trim()
+      if (project) args.push('--project', project)
+      const filter = String(params.filter ?? '').trim()
+      if (filter) args.push('--filter', filter)
+      if (params.files === true) args.push('--files')
+      return runPythonScript('project_resources.py', args)
+    },
+  })
+
+  pi.registerTool({
+    name: 'ignition_resource_read',
+    label: 'Ignition read resource',
+    description:
+      'Read a project resource file (view.json, .py, theme.css, resource.json, any text file) as pretty JSON or text. Binary files are refused.',
+    parameters: Type.Object({
+      path: Type.String({ description: 'Path relative to project root, e.g. com.inductiveautomation.perspective/views/mainView/view.json' }),
+      project: Type.Optional(Type.String({ description: 'Project name (default from config)' })),
+      max_chars: Type.Optional(Type.Number({ description: 'Truncate content at N chars (default 40000)' })),
+    }),
+    async execute(_id, params) {
+      const p = String(params.path ?? '').trim()
+      if (!p) return toolError('ignition_resource_read requires path.')
+      const args = ['--path', p]
+      const project = String(params.project ?? '').trim()
+      if (project) args.unshift('--project', project)
+      if (typeof params.max_chars === 'number' && params.max_chars > 0)
+        args.push('--max-chars', String(Math.floor(params.max_chars)))
+      return runPythonScript('resource_read.py', args)
+    },
+  })
+
+  pi.registerTool({
+    name: 'ignition_resource_write',
+    label: 'Ignition write resource',
+    description:
+      'GATED (write-allowlist): atomically write a project resource file. JSON must parse; forbidden targets (digest, .bin, thumbnails, .resources, gateway config) are refused. New resource folders get a scan-compatible resource.json scaffold. Follow with ignition_scan to hot-apply.',
+    parameters: Type.Object({
+      path: Type.String({ description: 'File path relative to project root' }),
+      content: Type.String({ description: 'Full file content (text/JSON)' }),
+      project: Type.Optional(Type.String({ description: 'Project name — must be enabled in the write-allowlist' })),
+    }),
+    async execute(_id, params) {
+      const p = String(params.path ?? '').trim()
+      const content = String(params.content ?? '')
+      if (!p) return toolError('ignition_resource_write requires path.')
+      if (!content) return toolError('ignition_resource_write requires non-empty content.')
+      const project = String(params.project ?? '').trim()
+      const staged = await stageContent(content)
+      const args = project ? ['--project', project] : []
+      args.push('--path', p, ...staged)
+      return runPythonScript('resource_write.py', args)
+    },
+  })
+
+  pi.registerTool({
+    name: 'ignition_validate',
+    label: 'Ignition validate resource',
+    description:
+      'Offline lint before writing/scanning: view.json structure + unique component names + binding shapes; Jython 2.7 compatibility for project scripts (f-strings are errors); resource.json key checks. Never touches the gateway.',
+    parameters: Type.Object({
+      path: Type.String({ description: 'Resource file path relative to project root' }),
+      project: Type.Optional(Type.String({ description: 'Project name (default from config)' })),
+    }),
+    async execute(_id, params) {
+      const p = String(params.path ?? '').trim()
+      if (!p) return toolError('ignition_validate requires path.')
+      const args = ['--path', p]
+      const project = String(params.project ?? '').trim()
+      if (project) args.unshift('--project', project)
+      return runPythonScript('validate.py', args)
+    },
+  })
+
+  pi.registerTool({
+    name: 'ignition_scan',
+    label: 'Ignition scan (hot-apply)',
+    description:
+      'GATED (allow_scan): trigger POST /data/api/v1/scan/{scope} to hot-apply on-disk edits into the gateway + open Designers. Warns when a Designer session is open. Polls until the scan completes. Scope=projects for view/tag/script edits; config for gateway config.',
+    parameters: Type.Object({
+      scope: Type.Optional(Type.String({ description: 'projects | config (default projects)' })),
+      wait_seconds: Type.Optional(Type.Number({ description: 'Max poll seconds (default 60)' })),
+    }),
+    async execute(_id, params) {
+      const args: string[] = []
+      const scope = String(params.scope ?? 'projects').trim()
+      if (scope) args.push('--scope', scope)
+      if (typeof params.wait_seconds === 'number' && params.wait_seconds > 0)
+        args.push('--wait', String(params.wait_seconds))
+      return runPythonScript('scan.py', args)
+    },
+  })
+
+  pi.registerTool({
+    name: 'ignition_project_create',
+    label: 'Ignition create project',
+    description:
+      'GATED (allow_project_create): create a NEW empty project via REST (isolated, low-risk) and scan it onto disk. Use for scratch/demo projects — then enable it in the write-allowlist to write its resources.',
+    parameters: Type.Object({
+      name: Type.String({ description: 'New project name (no spaces/slashes)' }),
+      title: Type.Optional(Type.String({ description: 'Display title (defaults to name)' })),
+      description: Type.Optional(Type.String({ description: 'Project description' })),
+    }),
+    async execute(_id, params) {
+      const name = String(params.name ?? '').trim()
+      if (!name) return toolError('ignition_project_create requires name.')
+      const args = ['--name', name]
+      const title = String(params.title ?? '').trim()
+      const desc = String(params.description ?? '').trim()
+      if (title) args.push('--title', title)
+      if (desc) args.push('--description', desc)
+      return runPythonScript('project_create.py', args)
+    },
+  })
+
+  pi.registerTool({
+    name: 'ignition_backup',
+    label: 'Ignition gateway backup',
+    description:
+      'Download a full gateway backup (.gwbk) via REST to ~/.ignition-sylo/backups/. Run before risky/bulk changes as the rollback safety net (restore via gateway web UI).',
+    parameters: Type.Object({
+      out: Type.Optional(Type.String({ description: 'Output .gwbk path (default ~/.ignition-sylo/backups/<timestamp>.gwbk)' })),
+    }),
+    async execute(_id, params) {
+      const out = String(params.out ?? '').trim()
+      const args = out ? ['--out', out] : []
+      return runPythonScript('backup.py', args)
+    },
+  })
+
+  pi.registerTool({
+    name: 'ignition_screenshot',
+    label: 'Ignition Perspective screenshot',
+    description:
+      'Screenshot a Perspective session page (uses installed Chrome/Edge — no browser download). Save path is returned; read it with analyze_image for the vision design-quality loop. Requires pip playwright (package requirements).',
+    parameters: Type.Object({
+      project: Type.Optional(Type.String({ description: 'Project name (default from config)' })),
+      path: Type.Optional(Type.String({ description: 'View path segment appended to the client URL' })),
+      url: Type.Optional(Type.String({ description: 'Full override URL (advanced)' })),
+      out: Type.Optional(Type.String({ description: 'Output PNG path' })),
+      width: Type.Optional(Type.Number({ description: 'Viewport width (default 1600)' })),
+      height: Type.Optional(Type.Number({ description: 'Viewport height (default 900)' })),
+      wait_ms: Type.Optional(Type.Number({ description: 'Render settle ms (default 9000)' })),
+    }),
+    async execute(_id, params) {
+      const args: string[] = []
+      const project = String(params.project ?? '').trim()
+      if (project) args.push('--project', project)
+      const p = String(params.path ?? '').trim()
+      if (p) args.push('--path', p)
+      const url = String(params.url ?? '').trim()
+      if (url) args.push('--url', url)
+      const out = String(params.out ?? '').trim()
+      if (out) args.push('--out', out)
+      if (typeof params.width === 'number') args.push('--width', String(params.width))
+      if (typeof params.height === 'number') args.push('--height', String(params.height))
+      if (typeof params.wait_ms === 'number') args.push('--wait-ms', String(params.wait_ms))
+      return runPythonScript('screenshot.py', args)
+    },
+  })
+
+  pi.registerTool({
+    name: 'ignition_gateway_logs',
+    label: 'Ignition gateway logs',
+    description:
+      'Read gateway logs via REST (filters: level, search, logger). Use when a scan fails or a resource does not appear — scan/resource errors land here.',
+    parameters: Type.Object({
+      limit: Type.Optional(Type.Number({ description: 'Max entries (default 100)' })),
+      min_level: Type.Optional(Type.String({ description: 'e.g. WARN or ERROR' })),
+      search: Type.Optional(Type.String({ description: 'Substring search in messages' })),
+      logger: Type.Optional(Type.String({ description: 'Logger name filter' })),
+    }),
+    async execute(_id, params) {
+      const args: string[] = []
+      if (typeof params.limit === 'number' && params.limit > 0) args.push('--limit', String(Math.floor(params.limit)))
+      const minLevel = String(params.min_level ?? '').trim()
+      if (minLevel) args.push('--min-level', minLevel)
+      const search = String(params.search ?? '').trim()
+      if (search) args.push('--search', search)
+      const logger = String(params.logger ?? '').trim()
+      if (logger) args.push('--logger', logger)
+      return runPythonScript('gateway_logs.py', args)
+    },
+  })
+
+  pi.registerTool({
+    name: 'ignition_api_get',
+    label: 'Ignition REST GET (read-only)',
+    description:
+      'Read-only GET passthrough to the 588-route gateway REST API (resource lists, gateway info, tag export, Perspective sessions...). GET only — mutating verbs are refused. Use --save for big payloads like /openapi.json.',
+    parameters: Type.Object({
+      route: Type.String({ description: 'GET route starting with /data/ (query string allowed), or /openapi.json' }),
+      save: Type.Optional(Type.String({ description: 'Save the full payload to this file path (recommended for large responses)' })),
+    }),
+    async execute(_id, params) {
+      const route = String(params.route ?? '').trim()
+      if (!route) return toolError('ignition_api_get requires route.')
+      const args = ['--route', route]
+      const save = String(params.save ?? '').trim()
+      if (save) args.push('--save', save)
+      return runPythonScript('api_get.py', args)
+    },
+  })
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "sylo-ignition",
+  "version": "0.1.0",
+  "description": "Ignition 8.3 gateway + project assistant — file-based resource authoring, REST scan/hot-reload, tag scaffolding, screenshot-verified Perspective UI",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "assets",
+    "extensions",
+    "scripts",
+    "skills",
+    "references/README.md",
+    "references/gateway-rest-api-8.3.md",
+    "references/quickref",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ],
+    "skills": [
+      "./skills/ignition",
+      "./skills/ignition-reference"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.2"
+  },
+  "dependencies": {
+    "typebox": "^1.1.24"
+  },
+  "license": "MIT"
+}

package/references/README.md

@@ -0,0 +1,45 @@
+# Ignition reference docs (offline)
+
+Offline Ignition documentation for the **sylo-ignition** package. Fetched
+2026-08-30 with `packages/sylo-ignition/scripts/fetch_docs.py` (requires
+pandoc 3.x; re-run any time to refresh — downloads are cached/resumable in
+`~/igscrape/html/`).
+
+> **Provenance.** Content is © Inductive Automation, scraped from their public
+> documentation sites for internal offline use. Every page records its source
+> URL under the title. Do not redistribute.
+
+## What's here
+
+| Path | Contents | Size |
+|------|----------|------|
+| `user-manual-8.3/` | **Ignition 8.3 User Manual** — 1566 pages as Markdown (tables, code blocks, internal links preserved). Mirrors `docs.inductiveautomation.com/docs/8.3/…` paths. | 28 MB |
+| `sdk-docs/` | **Ignition SDK Programmer's Guide (8.3)** — 63 pages as Markdown. Mirrors `sdk-docs.inductiveautomation.com/docs/8.3/…`. | 0.6 MB |
+| `user-manual-8.1-pdfs/` | **Official 8.1 manual PDF exports** (IA legacy-docs, taken 2024-02-21) — 17 files incl. Platform, Scripting Functions, Expression Functions, Perspective/Vision Components refs. Use with the **pdf-reader** skill (`search_schematic_pdf` etc.). *Git-ignored — re-fetch with `fetch_docs.py`.* | 262 MB |
+
+## How to use (agent notes)
+
+- **Search:** `grep -rn "<term>" user-manual-8.3 --include="*.md"` — pipe-table
+  and grid-table contents are all greppable. Prefer searching here over the web
+  for Ignition facts; cite the `> Source:` line when referencing.
+- **Key pages for the package:**
+  - `user-manual-8.3/platform/tags/tag-properties.md` — tag JSON property names + on-disk tag file paths
+  - `user-manual-8.3/tutorials/version-control-guide.md` — file-based config, `.gitignore`, scan endpoints
+  - `user-manual-8.3/platform/gateway/openapi.md` — REST API + API keys
+  - `user-manual-8.3/appendix/components/perspective-components/` — Perspective component catalog (per-component props/events)
+  - `user-manual-8.3/appendix/scripting-functions/` — Jython `system.*` function reference
+  - `user-manual-8.3/new-in-this-version.md` — 8.3.0→8.3.9 changelog deltas
+  - `sdk-docs/programming-for-the-gateway/storing-data-using-resource-collections.md` — the config resource model
+- **8.1 questions:** use the PDFs (`user-manual-8.1-pdfs/DOC-81-3-platform.pdf`,
+  `DOC-81-4-scripting-functions.pdf`, `DOC-81-6-2-perspective-components.pdf`, …)
+  via pdf-reader tools.
+
+## Known limitations
+
+- 4 pages skipped (no extractable content): the visual `/scopes/*` pages
+  (`scopes`, `gateway`, `perspective-session`, `vision-client`). Read them online if needed.
+- Images are **not** mirrored; image links point at the live site.
+- 1 page retains a raw HTML table (grid conversion failed) — content still greppable.
+- Admonitions (note/tip boxes) are flattened into plain paragraphs — look for
+  the bold title line ("Note", "Danger", …) that precedes them.
+- The 8.1 PDFs snapshot Feb 2024 — later 8.1.x point releases are not covered.

package/references/gateway-rest-api-8.3.md

@@ -0,0 +1,119 @@
+# Ignition 8.3 Gateway REST API — verified route map
+
+Verified live 2026-08-30 against a **native Windows Ignition 8.3.9** install
+(Perspective module 3.3.9), gateway at `http://localhost:8088`. Full OpenAPI
+spec: `GET /openapi.json` with the `X-Ignition-API-Token` header (12 MB on a
+full-module install, 588 routes). This file is the curated subset the
+sylo-ignition tools actually use.
+
+## Auth (verified recipe)
+
+- Create API key: **Platform → Security → API Keys → Create API Key +**
+  (Basic Token). Token shown once.
+- Key must have **"Require secure connections" unchecked** for plain-HTTP
+  local gateways (checked → 403 over HTTP).
+- Role-derived levels (Roles→Administrator) are **greyed out** for API keys.
+  Custom levels are assignable. Working setup (verified):
+  1. **Platform → Security → Levels**: add custom level `SyloAPI` under
+     `Authenticated`
+  2. Assign `SyloAPI` to the API key
+  3. **Platform → Security → General Settings → Roles and Permissions**:
+     check `SyloAPI` for Gateway Read AND Gateway Write permissions
+- Every request: header `X-Ignition-API-Token: <token>`.
+- Status codes: bad/dead token → 401; insufficient security level → 403
+  (route exists); no such route → 404 (`No route match for path: /v1/...`).
+
+## Scan / safe-edit protocol
+
+| Method | Route | Purpose |
+|--------|-------|---------|
+| GET  | `/data/api/v1/scan/projects` | Project scan status (`scanActive`, `lastScanTimestamp`) |
+| POST | `/data/api/v1/scan/projects` | **Trigger project scan** — hot-loads disk edits into gateway + Designer |
+| GET/POST | `/data/api/v1/scan/config` | Same for gateway config (`data/config/**`) |
+| GET  | `/data/api/v1/scan-lock/projects` | Scan-lock info |
+| POST | `/data/api/v1/scan-lock/projects` | Acquire project scan lock (mutual exclusion while writing on disk) |
+| GET  | `/data/api/v1/sync/items` | Config sync status |
+| POST | `/data/api/v1/sync/reset` | Reset config sync |
+
+## Projects API
+
+| Method | Route | Purpose |
+|--------|-------|---------|
+| GET    | `/data/api/v1/projects/list` | List all projects (with resource counts) |
+| GET    | `/data/api/v1/projects/names` | Project names |
+| POST   | `/data/api/v1/projects` | Create project |
+| GET    | `/data/api/v1/projects/find/{name}` | Project details |
+| PUT    | `/data/api/v1/projects/{name}` | Modify project (title/description/enabled/parent) |
+| DELETE | `/data/api/v1/projects/{name}` | Delete project |
+| POST   | `/data/api/v1/projects/copy` | Copy project |
+| POST   | `/data/api/v1/projects/rename/{name}` | Rename project |
+| GET    | `/data/api/v1/projects/export/{name}` | **Export project zip** |
+| POST   | `/data/api/v1/projects/import/{name}` | **Import project zip** |
+
+## Resources API (gateway config, pattern per type)
+
+Pattern per resource type (393 routes total):
+`GET /data/api/v1/resources/list|names|type|find|rename|delete/{moduleId}/{typeId}`,
+`PUT|POST /data/api/v1/resources/{moduleId}/{typeId}` (create/update),
+`GET|PUT|DELETE .../datafile/{moduleId}/{typeId}/{name}/{filename}` (attached files),
+`GET .../singleton/{moduleId}/{typeId}` (singletons).
+
+Key types for sylo-ignition:
+
+| Module | Type | Use |
+|--------|------|-----|
+| `ignition` | `tag-provider` | Tag provider CRUD |
+| `com.inductiveautomation.opcua` | `device` | OPC UA device connections |
+| `ignition` | `opc-connection` | Legacy OPC connections |
+| `ignition` | `database-connection` | DB connections |
+| `com.inductiveautomation.perspective` | `themes` | **Theme resources** (theme.json + css files via datafile routes) |
+| `com.inductiveautomation.perspective` | `fonts`, `icons` | Fonts / icon sets |
+| `ignition` | `security-levels`, `security-properties`, `security-zone` | Security config |
+| `ignition` | `identity-provider`, `user-source` | Authn config |
+
+## Tags
+
+| Method | Route | Purpose |
+|--------|-------|---------|
+| GET  | `/data/api/v1/tags/export` | **Download tag export (JSON)** — provider/tag paths, recursive |
+| POST | `/data/api/v1/tags/import` | **Import tags (JSON)** — create/override, collision handling |
+| PUT  | `/data/api/v1/managed-tag-provider` | Write managed tag provider definitions |
+
+No REST route for tag **values** (definitions only). Value read/write goes
+through the gateway's OPC-UA server or scripting, not this API.
+
+## Perspective module API
+
+| Method | Route | Purpose |
+|--------|-------|---------|
+| GET    | `/data/perspective/api/v1/sessions/` | Live sessions |
+| GET    | `/data/perspective/api/v1/session/{sessionId}` | Session detail |
+| GET    | `/data/perspective/api/v1/session/{sessionId}/pages` | Pages in session |
+| GET    | `/data/perspective/api/v1/session/{sessionId}/page/{pageId}/views` | Mounted views |
+| DELETE | `/data/perspective/api/v1/sessions` | Terminate session(s) |
+| POST   | `/data/perspective/api/v1/themes/copy-base-themes` | **Copy base themes into project** (start of theme customization) |
+
+## Gateway status / diagnostics
+
+| Method | Route | Purpose |
+|--------|-------|---------|
+| GET  | `/data/api/v1/gateway-info` | Version/edition/platform info |
+| GET  | `/data/api/v1/overview` | Gateway overview (modules, system) |
+| GET  | `/data/api/v1/overview/problems` | Health problems list |
+| GET  | `/data/api/v1/overview/connections` | Connection statuses |
+| GET  | `/data/api/v1/logs` | Gateway logs (debug scan failures etc.) |
+| GET  | `/data/api/v1/logs/download` | Download logs |
+| GET  | `/data/api/v1/backup` | **Gateway backup download** (pre-change safety) |
+| POST | `/data/api/v1/backup` | Restore backup |
+| GET  | `/data/api/v1/designers` | Open Designer sessions (conflict detection!) |
+| GET  | `/data/api/v1/entity/browse` | Browse config entities |
+| GET/POST/PUT/DELETE | `/data/api/v1/mode*` | Deployment modes |
+| GET  | `/data/api/v1/licenses` | License info |
+| GET  | `/data/api/v1/trial` | Trial info |
+
+## OPC-UA module API (client/server PKI)
+
+`/data/opc-ua/api/v1/...` — trust/reject/download/upload certificates for
+client & server PKI, regenerate server certificate. Needed for connecting to
+real PLCs (Logix/Modbus/Siemens etc. are driver configs via resources API:
+`com.inductiveautomation.opcua/device`).

package/references/quickref/README.md

@@ -0,0 +1,12 @@
+# Ignition 8.3 quick reference (bundled with the skill)
+
+This small folder is copied to `~/.pi/agent/references/ignition/` so the
+essentials travel with the skill. The **full** corpus (1,566-page User Manual +
+SDK docs as Markdown) stays in the Sylo repo at
+`packages/sylo-ignition/references/` — see `ignition-reference` SKILL.md.
+
+- `gateway-rest-api-8.3.md` — verified route map of the 588-route REST API,
+  the working API-key security-level recipe, and per-area tables (projects,
+  scan, resources, tags, Perspective, diagnostics).
+- `formats-quickref.md` — on-disk layout, view.json, bindings, resource.json,
+  Jython 2.7 notes.