@gizai/cli 1.1.0 → 1.3.0

package/README.md

@@ -5,7 +5,7 @@ Connect once in the browser, then use live Giz text and media models, Drive, and
 ```bash
 npm install -g @gizai/cli
 giz auth login
-giz chat gpt-5-6-luna "Say hello in Korean"
+giz chat gpt-6-luna "Say hello in Korean"
 giz generate image "A paper observatory at blue hour"
 ```
 
@@ -77,3 +77,91 @@ that runtime. Media jobs run independently and are tracked with `giz job get`.
 Create a scoped API key with `giz api-key create "My app"`; its secret is shown once. Set `GIZ_TOKEN` only for ephemeral automation. Run `giz --help` for chat, models, Drive, Computer, job, upload, and raw tool commands.
 
 Documentation: <https://www.giz.ai/mcp/>
+
+### Managed Giz Computers
+
+Giz Computers receive the same CLI source through the Region release overlay, at
+`/opt/giz/managed/apps/giz-cli`, with `/opt/giz/managed/bin/giz` first on PATH.
+No npm installation or browser login is needed inside a managed Computer:
+
+```sh
+giz auth status
+giz drive ls
+giz model list
+```
+
+The Region owns `/opt/giz/identity/identity.sock` and exchanges the Computer identity for a
+15-minute access token. For this release only, when the new socket path is absent,
+the CLI reads `/run/giz/identity.sock` to support an overlay arriving before its
+gateway update. No environment variable can override the socket path. The CLI
+caches it only in memory; it never saves a refresh
+token or API key for this identity. `giz auth status` displays
+`컴퓨터 신원으로 로그인됨 (소유자 <email>)`. A saved `giz auth login` takes priority;
+`giz auth logout` removes that user login and returns to the Computer identity.
+Shared Computers can access only their own Drive, model discovery/inference, and
+jobs started by that Computer. API key, billing, organization administration,
+destructive operations and external writes require a separate user authorization.
+The managed `giz --version` includes the Region source revision; npm installations
+continue to report the package version. Existing Computers receive overlay updates
+without recreation. The Region's normal release activation attaches identity sockets
+for existing instances, and socket replacement remains visible through the directory mount.
+
+App 변경은 `giz app list`에서 확인한 `revision`을 명시적으로 전달합니다.
+`run`, `publish`, `delete`에는 `--expected-revision REVISION`이 필요합니다.
+`create`/`save`의 `--input`에는 `id`와 `expectedRevision`을 넣습니다(새 앱은 0).
+목록을 다시 읽어 개정 번호를 자동 대체하지 않으므로, 검토 뒤 다른 변경이 생기면 서버가 충돌을 거부합니다.
+
+아래 표는 CLI 디스패처와 도구 item에서 생성합니다. 갱신 명령:
+`GIZ_UPDATE_CLI_SURFACE=1 pnpm --filter giz-app-giz test --runInBand --runTestsByPath server/external/cli-surface.spec.ts`.
+일반 CI 실행은 문서를 쓰지 않고 표의 차이를 실패로 보고합니다.
+
+<!-- cli-surface:start -->
+| CLI 명령 | 도구 ID | MCP 이름 | 필수 입력 | scope | Agent 발견 |
+| --- | --- | --- | --- | --- | --- |
+| model list | model.list | model_list | - | giz.read | model.list |
+| model get | model.get | model_get | model | giz.read | model.get |
+| model run | model.run | model_run | model, input | giz.inference | model.run |
+| generate image | generateImage | generateImage | prompt | giz.write | generateImage |
+| generate video | generateVideo | generateVideo | prompt | giz.write | generateVideo |
+| generate music | generateMusic | generateMusic | prompt | giz.write | generateMusic |
+| generate talking-head | generateTalkingHead | generateTalkingHead | prompt, references | giz.write | generateTalkingHead |
+| generate audio | generateAudio | generateAudio | purpose | giz.write | generateAudio |
+| job list | job.list | job_list | - | giz.read | server job |
+| job get | job.get | job_get | job | giz.read | server job |
+| job wait | job.get | job_get | job | giz.read | server job |
+| job cancel | job.cancel | job_cancel | job | giz.destructive | server job |
+| credits | account.credits | account_credits | - | giz.read | account.credits |
+| drive ls | drive.list | drive_list | - | giz.read | drive.list |
+| drive list | drive.list | drive_list | - | giz.read | drive.list |
+| drive search | drive.search | drive_search | query | giz.read | drive.search |
+| drive read | drive.readFile | drive_readFile | path | giz.read | drive.readFile |
+| drive write | drive.writeFile | drive_writeFile | path, content | giz.write | drive.writeFile |
+| drive mkdir | drive.makeDirectory | drive_makeDirectory | path | giz.write | drive.makeDirectory |
+| drive move | drive.movePath | drive_movePath | from, to | giz.write | drive.movePath |
+| drive delete | drive.deletePath | drive_deletePath | path | giz.destructive | drive.deletePath |
+| table list | workspace.objects | workspace_objects | - | giz.read | workspace.objects |
+| table get | workspace.objects | workspace_objects | - | giz.read | workspace.objects |
+| table read | table.readRows | table_readRows | table | giz.read | table.readRows |
+| table write | table.writeRows | table_writeRows | table | giz.write | table.writeRows |
+| table action | workspace.executeAction | workspace_executeAction | view, action | giz.execute | workspace.executeAction |
+| computer list | computer.list | computer_list | - | giz.read | computer.list |
+| computer get | computer.get | computer_get | - | giz.read | external only |
+| computer start | computer.start | computer_start | - | giz.execute | external only |
+| computer stop | computer.stop | computer_stop | - | giz.destructive | external only |
+| computer exec | computer.exec | giz_computer_exec | - | giz.execute | computer.exec |
+| app list | app.list | app_list | - | giz.read | app.list |
+| app create | app.save | app_save | id, expectedRevision | giz.execute | app.save |
+| app save | app.save | app_save | id, expectedRevision | giz.execute | app.save |
+| app run | app.run | app_run | id, expectedRevision | giz.execute | app.run |
+| app publish | app.publish | app_publish | id, expectedRevision, visibility | giz.write | app.publish |
+| app open | app.open | app_open | id | giz.read | app.open |
+| app delete | app.delete | app_delete | id, expectedRevision | giz.destructive | app.delete |
+| capability list | capability.status | capability_status | - | giz.read | capability.status |
+| capability search | capability.catalog | capability_catalog | kind, query | giz.read | capability.catalog |
+| capability install | capability.install | capability_install | id, kind, query | giz.execute | capability.install |
+| capability update | capability.manage | capability_manage | id, operation | giz.destructive | capability.manage |
+| capability remove | capability.manage | capability_manage | id, operation | giz.destructive | capability.manage |
+| agent start | agent.start | agent_start | agentId, prompt | giz.execute | external only |
+| agent status | agent.status | agent_status | turnId | giz.read | agent.status |
+| agent cancel | agent.cancel | agent_cancel | turnId | giz.execute | agent.cancel |
+<!-- cli-surface:end -->

package/cli/codex-relay.mjs

@@ -0,0 +1,46 @@
+// Runs ONLY inside the user's Computer. stdout is the authenticated gateway wire,
+// never credentials or provider error bodies. No listener or separate credential store.
+import { readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { execFileSync } from 'node:child_process'
+
+const emit = value => process.stdout.write(JSON.stringify(value) + '\n')
+try {
+  const auth = JSON.parse(await readFile(join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'auth.json'), 'utf8'))
+  const token = auth.tokens?.access_token
+  const account = auth.tokens?.account_id
+  if (auth.OPENAI_API_KEY || !token || !account) {
+    emit({ status: 401 }); process.exitCode = 1
+  } else {
+    const headers = { authorization: `Bearer ${token}`, 'chatgpt-account-id': account, 'content-type': 'application/json', originator: 'codex_cli_rs' }
+    const mode = process.argv[2]
+    if (mode === 'models') {
+      const version = execFileSync('codex', ['--version'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim().split(' ').at(-1)
+      const response = await fetch(`https://chatgpt.com/backend-api/codex/models?client_version=${encodeURIComponent(version)}`, { headers, signal: AbortSignal.timeout(30000) })
+      if (!response.ok) emit({ status: response.status })
+      else {
+        const payload = await response.json()
+        emit({ status: 200, models: (payload.models || []).filter(model => model.visibility !== 'hide').map(model => ({ id: model.slug, label: model.display_name || model.slug })).filter(model => typeof model.id === 'string' && model.id.length <= 256) })
+      }
+    } else if (mode === 'responses') {
+      let input = ''
+      for await (const chunk of process.stdin) input += chunk
+      const body = JSON.parse(input)
+      body.store = false
+      body.stream = true
+      body.instructions ??= ''
+      delete body.max_output_tokens
+      delete body.temperature
+      delete body.top_p
+      const response = await fetch('https://chatgpt.com/backend-api/codex/responses', { method: 'POST', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(300000) })
+      emit({ status: response.status })
+      if (response.ok) {
+        for await (const chunk of response.body) emit({ chunk: Buffer.from(chunk).toString('base64') })
+        emit({ done: true })
+      }
+    } else emit({ status: 400 })
+  }
+} catch {
+  emit({ status: 503 }); process.exitCode = 1
+}

package/cli/computer-identity.mjs

@@ -0,0 +1,76 @@
+import { lstat, readFile } from 'node:fs/promises'
+import { request } from 'node:http'
+
+export const IDENTITY_SOCKET = '/opt/giz/identity/identity.sock'
+
+// One-release bridge: the managed CLI overlay can arrive before the Region gateway migration.
+export async function resolveIdentitySocket() {
+  try {
+    await lstat(IDENTITY_SOCKET)
+    return IDENTITY_SOCKET
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error
+    return '/run/giz/identity.sock'
+  }
+}
+let cached
+let pending
+
+// The release overlay owns this stamp; outside npm installations do not have it.
+export async function managedRevision() {
+  return readFile(new URL('../REVISION', import.meta.url), 'utf8').catch(error => {
+    if (error.code !== 'ENOENT') throw error
+  })
+}
+
+// The CLI never accepts a socket path from options, environment, or request data.
+export async function computerIdentity(rejectedToken) {
+  if (cached?.access_token !== rejectedToken && cached?.expires_at > Date.now() + 60_000) return cached
+  pending ??= resolveIdentitySocket().then(socketPath => new Promise((resolve, reject) => {
+    const req = request({ socketPath, path: '/token', method: 'POST',
+      headers: { 'content-length': '0' } }, res => {
+      let body = ''
+      res.setEncoding('utf8')
+      res.on('data', chunk => {
+        body += chunk
+        if (body.length > 16_384) req.destroy(new Error('컴퓨터 신원 응답이 너무 큽니다.'))
+      })
+      res.on('error', reject)
+      res.on('end', () => {
+        try {
+          const value = JSON.parse(body)
+          if (res.statusCode !== 200) throw new Error(value.error_description || value.message || '컴퓨터 신원을 사용할 수 없습니다.')
+          const url = new URL(value.baseUrl)
+          if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password ||
+              url.pathname !== '/' || url.search || url.hash || !value.access_token ||
+              value.token_type !== 'Bearer' || Number(value.expires_in) <= 0 || Number(value.expires_in) > 900) {
+            throw new Error('컴퓨터 신원 응답이 올바르지 않습니다.')
+          }
+          cached = { access_token: value.access_token, baseUrl: url.origin,
+            expires_at: Date.now() + Number(value.expires_in) * 1000 }
+          resolve(cached)
+        } catch (error) { reject(error) }
+      })
+    })
+    req.on('error', async error => {
+      if (error.code !== 'ENOENT') return reject(error)
+      try {
+        await lstat(socketPath)
+        reject(new Error('컴퓨터 신원 서비스에 연결할 수 없습니다. 잠시 후 다시 시도해 주세요.'))
+      } catch (lookupError) {
+        if (lookupError.code !== 'ENOENT') return reject(lookupError)
+        try {
+          if (await managedRevision() !== undefined) {
+            reject(new Error('컴퓨터 신원을 확인할 수 없습니다. 잠시 후 다시 시도하거나 소유자에게 문의해 주세요.'))
+          } else resolve(undefined)
+        } catch (error) { reject(error) }
+      }
+    })
+    req.setTimeout(10_000, () => req.destroy(new Error('컴퓨터 신원 응답 시간이 초과되었습니다.')))
+    req.end()
+  })).catch(error => {
+    error.hint = '컴퓨터 상태를 확인하고 다시 시도해 주세요. 차단되었다면 소유자 또는 조직 관리자에게 문의해 주세요.'
+    throw error
+  }).finally(() => { pending = undefined })
+  return pending
+}

package/cli/engine.mjs

@@ -0,0 +1,58 @@
+import { spawn, execFileSync } from 'node:child_process'
+import { mkdir } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import path from 'node:path'
+
+/** Local Computer execution: official binary, existing permissions, isolated reviewable worktree. */
+export async function runEngine(engine, instruction, directory = process.cwd(), progress = () => {}) {
+  if (engine !== 'claude' || typeof instruction !== 'string' || !instruction.trim()) throw new Error('Run: giz engine run claude "instruction" [--dir path]')
+  const git = (args, cwd = directory) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 8 * 1024 * 1024 })
+  const env = { ...process.env }
+  for (const key of ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_BASE_URL', 'CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY']) delete env[key]
+  const status = spawn('claude', ['auth', 'status'], { env, stdio: ['ignore', 'pipe', 'ignore'] })
+  let login = ''
+  status.stdout.on('data', chunk => { login += chunk })
+  await new Promise((resolve, reject) => { status.once('error', reject); status.once('close', code => code === 0 ? resolve() : reject(new Error('Log in to Claude Code in Connections.'))) })
+  const account = JSON.parse(login)
+  if (!account.loggedIn || account.authMethod !== 'claude.ai') throw new Error('A Claude subscription login is required.')
+  const root = git(['rev-parse', '--show-toplevel']).trim()
+  const common = path.resolve(root, git(['rev-parse', '--git-common-dir']).trim())
+  const worktree = path.join(common, 'giz-engine-worktrees', randomUUID())
+  await mkdir(path.dirname(worktree), { recursive: true })
+  git(['worktree', 'add', '--detach', worktree, 'HEAD'])
+  progress({ status: 'running', engine, worktree })
+  const child = spawn('claude', ['-p', instruction, '--output-format', 'stream-json', '--verbose', '--permission-mode', 'acceptEdits'],
+    { cwd: worktree, env, detached: true, stdio: ['ignore', 'pipe', 'pipe'] })
+  let output = '', summary = '', stopped = false
+  const stop = () => { stopped = true; try { process.kill(-child.pid, 'SIGTERM') } catch {} }
+  process.once('SIGTERM', stop); process.once('SIGINT', stop)
+  child.stdout.on('data', chunk => {
+    output += chunk
+    let newline
+    while ((newline = output.indexOf('\n')) >= 0) {
+      const line = output.slice(0, newline); output = output.slice(newline + 1)
+      try {
+        const event = JSON.parse(line)
+        if (event.type === 'result') summary = String(event.result || '')
+        // Do not pass raw tool inputs, prompts or authorization data into the task card.
+        progress({ status: 'running', event: event.type, engine, worktree })
+      } catch {}
+    }
+  })
+  child.stderr.resume()
+  let exitCode
+  try {
+    exitCode = await new Promise((resolve, reject) => { child.once('error', reject); child.once('close', code => resolve(code)) })
+  } finally { process.removeListener('SIGTERM', stop); process.removeListener('SIGINT', stop) }
+  const tracked = git(['diff', '--name-only', 'HEAD'], worktree).trim().split('\n').filter(Boolean)
+  const created = git(['ls-files', '--others', '--exclude-standard'], worktree).trim().split('\n').filter(Boolean)
+  let diff = git(['diff', '--binary', 'HEAD'], worktree)
+  for (const file of created) {
+    try { diff += git(['diff', '--no-index', '--binary', '--', '/dev/null', file], worktree) }
+    catch (error) {
+      if (error.status !== 1) throw error
+      diff += String(error.stdout)
+    }
+  }
+  return { status: stopped ? 'canceled' : exitCode === 0 ? 'completed' : 'failed', engine, exitCode, worktree, files: [...new Set([...tracked, ...created])], diff, summary }
+}

package/cli/giz.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { computerIdentity, managedRevision } from './computer-identity.mjs'
 import { createHash, randomBytes } from 'node:crypto'
 import { openAsBlob } from 'node:fs'
 import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'
@@ -18,7 +19,7 @@ const { version: CLI_VERSION } = createRequire(import.meta.url)('../package.json
 const DEFAULT_URL = 'https://www.giz.ai'
 const CLIENT_ID = 'giz-cli'
 const SCOPES = ['giz.read', 'giz.inference', 'giz.write', 'giz.execute', 'giz.destructive', 'offline_access']
-const BOOLEAN_OPTIONS = new Set(['help', 'json', 'no-open', 'version'])
+const BOOLEAN_OPTIONS = new Set(['help', 'json', 'no-open', 'version', 'device'])
 const configPath = path.resolve(process.env.GIZ_CONFIG ||
   path.join(os.homedir(), '.config', 'giz', 'credentials.json'))
 
@@ -113,10 +114,9 @@ async function exchangeToken(baseUrl, metadata, grant, config = {}) {
   })
   const payload = await response.json()
   if (!response.ok) {
-    throw new CliError(
-      payload.error_description || payload.error || 'OAuth token exchange failed.',
-      'Run: giz auth login'
-    )
+    const error = new CliError(payload.error_description || payload.error || 'OAuth token exchange failed.', 'Run: giz auth login')
+    error.oauthError = payload.error
+    throw error
   }
   return {
     ...config,
@@ -130,7 +130,12 @@ async function exchangeToken(baseUrl, metadata, grant, config = {}) {
 async function credentials(baseUrl, rejectedToken) {
   if (process.env.GIZ_TOKEN) return { access_token: process.env.GIZ_TOKEN, baseUrl }
   const config = await readConfig()
-  if (!config?.access_token) throw new CliError('Not authenticated.', 'Run: giz auth login')
+  if (!config?.access_token) {
+    const computer = await computerIdentity(rejectedToken)
+    if (!computer) throw new CliError('Not authenticated.', 'Run: giz auth login')
+    if (computer.baseUrl !== baseUrl) throw new CliError('컴퓨터 신원은 다른 서버에서 사용할 수 없습니다.', '사용자 계정으로 giz auth login을 실행해 주세요.')
+    return computer
+  }
   if (String(config.baseUrl).replace(/\/+$/, '') !== baseUrl) {
     throw new CliError(
       `Credentials belong to ${config.baseUrl}.`,
@@ -159,6 +164,8 @@ async function authenticatedFetch(baseUrl, url, init = {}) {
   const signal = AbortSignal.timeout(25 * 60_000)
   const send = () => {
     headers.set('authorization', `Bearer ${auth.access_token}`)
+    // The server resolves membership and roles; the CLI only names the organization, as the web's selector does.
+    if (process.env.GIZ_ORGANIZATION) headers.set('x-giz-organization', process.env.GIZ_ORGANIZATION)
     return fetch(url, { ...init, headers, signal: init.signal ? AbortSignal.any([init.signal, signal]) : signal })
   }
   let response = await send()
@@ -179,6 +186,17 @@ async function jsonResponse(response, baseUrl) {
   }
   if (!response.ok) {
     const message = payload?.message || payload?.error?.message || `Giz API returned HTTP ${response.status}.`
+    // Older servers have only the legacy message; classify that exact contract without hiding other 404s.
+    if (response.status === 404 && (payload?.code === 'EXTERNAL_TOOL_UNAVAILABLE' ||
+        (new URL(response.url).pathname.startsWith('/api/tools/') && /^Unknown Giz tool: /.test(message)))) {
+      const compatibility = payload?.code === 'EXTERNAL_TOOL_UNAVAILABLE'
+        ? message : '서버 버전은 확인할 수 없습니다(구버전 서버).'
+      throw new CliError(
+        `이 서버는 요청한 명령을 지원하지 않습니다. CLI ${CLI_VERSION}. ${compatibility}`,
+        `서버 주소(${baseUrl})와 지원 버전을 확인해 주세요. 지원하는 서버는 --base-url로 선택할 수 있습니다.`,
+        response.status
+      )
+    }
     throw new CliError(
       message,
       response.status === 403 && /scope/i.test(message)
@@ -196,7 +214,16 @@ async function api(baseUrl, pathname, data, options = {}) {
     headers: { accept: 'application/json', ...(data === undefined ? {} : { 'content-type': 'application/json' }) },
     ...(data === undefined ? {} : { body: JSON.stringify(data) })
   })
-  return await jsonResponse(response, baseUrl)
+  const payload = await jsonResponse(response, baseUrl)
+  if (pathname === '/api/external/me' && payload.minimumCliVersion) {
+    const current = CLI_VERSION.split('.').map(Number)
+    const minimum = String(payload.minimumCliVersion).split('.').map(Number)
+    const differing = minimum.findIndex((part, index) => part !== current[index])
+    if (differing >= 0 && current[differing] < minimum[differing]) {
+      process.stderr.write(`Warning: Giz CLI ${CLI_VERSION} is below minimum ${payload.minimumCliVersion}; update @gizai/cli.\n`)
+    }
+  }
+  return payload
 }
 
 async function uploadMedia(baseUrl, localFile) {
@@ -215,6 +242,7 @@ async function uploadMedia(baseUrl, localFile) {
 
 async function login(baseUrl, options) {
   const metadata = await discovery(baseUrl)
+  if (options.device === true) return await deviceLogin(baseUrl, metadata)
   const verifier = randomBytes(48).toString('base64url')
   const challenge = createHash('sha256').update(verifier).digest('base64url')
   const state = randomBytes(24).toString('base64url')
@@ -240,6 +268,41 @@ async function login(baseUrl, options) {
   return await api(baseUrl, '/api/external/me')
 }
 
+async function deviceLogin(baseUrl, metadata) {
+  if (!metadata.device_authorization_endpoint) throw new CliError('OAuth device authorization is not supported.')
+  const response = await fetch(metadata.device_authorization_endpoint, {
+    method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({ client_id: CLIENT_ID, scope: SCOPES.join(' '), resource: new URL('/api/mcp', baseUrl).href }),
+    signal: AbortSignal.timeout(30_000)
+  })
+  const device = await response.json()
+  if (!response.ok) throw new CliError(device.error_description || device.error || 'OAuth device authorization failed.')
+  if (!device.device_code || !device.user_code || !device.verification_uri || !(Number(device.expires_in) > 0)) {
+    throw new CliError('OAuth device authorization returned an incomplete response.')
+  }
+  process.stderr.write(`Giz sign-in: ${device.verification_uri_complete || device.verification_uri}\nCode: ${device.user_code}\n`)
+  let interval = Number(device.interval ?? 5) * 1000
+  if (!Number.isFinite(interval) || interval <= 0) throw new CliError('OAuth device authorization returned an invalid interval.')
+  const deadline = Date.now() + Number(device.expires_in) * 1000
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now()
+    await new Promise((resolve) => setTimeout(resolve, Math.min(interval, remaining)))
+    if (interval >= remaining || Date.now() >= deadline) break
+    try {
+      await updateConfig(() => exchangeToken(baseUrl, metadata, {
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code', device_code: device.device_code
+      }))
+    } catch (error) {
+      if (error.oauthError === 'slow_down') interval += 5000
+      else if (error.name === 'TimeoutError') interval *= 2
+      else if (error.oauthError !== 'authorization_pending') throw error
+      continue
+    }
+    return await api(baseUrl, '/api/external/me')
+  }
+  throw new CliError('expired_token: Giz device code expired.', 'Run: giz auth login --device')
+}
+
 async function waitForCallback(expectedState) {
   const server = createServer()
   server.listen(0, '127.0.0.1')
@@ -286,6 +349,23 @@ function openBrowser(url) {
   child.unref()
 }
 
+// --input @FILE and --input - (stdin) carry JSON too large for one process argument (Linux caps one at 128 KiB).
+async function inputText(value) {
+  if (value === '-') {
+    let text = ''
+    for await (const chunk of process.stdin) text += chunk
+    return text
+  }
+  if (typeof value === 'string' && value.startsWith('@')) {
+    try {
+      return await readFile(value.slice(1), 'utf8')
+    } catch {
+      throw new CliError(`Could not read ${value.slice(1)}.`, 'Pass --input @PATH to an existing JSON file.')
+    }
+  }
+  return value
+}
+
 function jsonInput(value) {
   if (value === undefined || value === true) return {}
   try {
@@ -320,6 +400,19 @@ async function applyUploads(baseUrl, input, values = []) {
   return input
 }
 
+// Mutations use the user's reviewed App revision; fetching it silently would bypass conflict protection.
+function appRevision(options) {
+  const raw = options['expected-revision']
+  if (raw === undefined || raw === '') {
+    throw new CliError('개정 번호가 필요합니다.', 'giz app list에서 확인한 revision을 --expected-revision으로 전달해 주세요.')
+  }
+  const revision = Number(raw)
+  if (typeof raw !== 'string' || !/^\d+$/.test(raw) || !Number.isSafeInteger(revision) || revision < 1 || revision > 9_007_199_254_740_990) {
+    throw new CliError('개정 번호는 1 이상의 안전한 정수여야 합니다.', 'giz app list에서 현재 revision을 확인해 주세요.')
+  }
+  return revision
+}
+
 async function invoke(baseUrl, tool, input) {
   return await api(baseUrl, `/api/tools/${encodeURIComponent(tool)}`, input)
 }
@@ -353,8 +446,26 @@ async function serveMcp(baseUrl) {
 
 async function runCommand(baseUrl, positionals, options) {
   const [command, subcommand, ...rest] = positionals
-  if (options.version === true) return { kind: 'message', value: CLI_VERSION }
-  if (!command || command === 'help' || options.help === true) return { kind: 'help', value: help(command) }
+  if (options.version === true) {
+    const revision = await managedRevision()
+    return { kind: 'message', value: CLI_VERSION + (revision ? ` (region ${revision.trim()})` : '') }
+  }
+  if (!command || command === 'help' || options.help === true) {
+    // A script that asks for help on a command that does not exist must fail, not read the overview as success.
+    if (command && command !== 'help' && !help().split('\n').some((line) => line.trim().split(' ')[1] === command && line.startsWith('  giz '))) {
+      throw new CliError(`Unknown command "${command}".`, 'Run: giz --help')
+    }
+    return { kind: 'help', value: help(command) }
+  }
+  if (command === 'engine' && subcommand === 'run') {
+    if (rest[0] !== 'claude') throw new CliError('Only Claude Code is an engine connection.')
+    await api(baseUrl, '/api/external/engine/claude/authorization')
+    const { runEngine } = await import('./engine.mjs')
+    const result = await runEngine(rest[0], required(rest[1], 'INSTRUCTION', 'Run: giz engine run claude "instruction"'), options.dir,
+      event => process.stdout.write(JSON.stringify(event) + '\n'))
+    if (result.status !== 'completed') process.exitCode = 1
+    return { kind: 'result', value: result }
+  }
   if (command === 'auth' && subcommand === 'login') {
     return { kind: 'auth', value: await login(baseUrl, options) }
   }
@@ -400,6 +511,11 @@ async function runCommand(baseUrl, positionals, options) {
     }
   }
 
+  if (command === 'credits') {
+    // Batch scripts read the balance before paid work instead of learning it from a refusal (MCP-TOOL-SCHEMA-LIMITS).
+    if (subcommand) throw new CliError(`Unknown command "credits ${subcommand}".`, 'Run: giz credits')
+    return { kind: 'result', value: await invoke(baseUrl, 'account.credits', {}) }
+  }
   if (command === 'model' && subcommand === 'list') {
     return {
       kind: 'models',
@@ -456,7 +572,6 @@ async function runCommand(baseUrl, positionals, options) {
       ...(rest.length ? { prompt: rest.join(' ') } : {}),
       ...(options.model ? { model: options.model } : {})
     }, uploads)
-    required(input.prompt, 'PROMPT', `Run: giz generate ${subcommand} "your prompt"`)
     return { kind: 'job', value: await invoke(baseUrl, tool, input) }
   }
 
@@ -513,7 +628,7 @@ async function runCommand(baseUrl, positionals, options) {
         })
       }
     }
-    const mapping = mappings[subcommand]
+    const mapping = mappings[subcommand === 'ls' ? 'list' : subcommand]
     if (!mapping) throw new CliError(`Unknown drive command "${subcommand || ''}".`, 'Run: giz drive --help')
     const [tool, input] = mapping()
     return {
@@ -522,6 +637,37 @@ async function runCommand(baseUrl, positionals, options) {
     }
   }
 
+  if (command === 'table' && subcommand === 'list') {
+    return { kind: 'result', value: await invoke(baseUrl, 'workspace.objects', {}) }
+  }
+
+  if (command === 'table' && subcommand === 'get') {
+    const object = required(rest[0], 'TABLE', 'Run: giz table get task')
+    return { kind: 'result', value: await invoke(baseUrl, 'workspace.objects', { object }) }
+  }
+
+  if (command === 'table' && subcommand === 'action') {
+    const view = required(rest[0], 'TABLE', 'Run: giz table action TABLE ACTION [--id ID] --input JSON')
+    const action = required(rest[1], 'ACTION', 'Run: giz table get TABLE to see its actions')
+    const id = options.id === undefined ? undefined : String(options.id).includes(',') ? String(options.id).split(',') : String(options.id)
+    return {
+      kind: 'result',
+      value: await invoke(baseUrl, 'workspace.executeAction', { view, action, ...(id === undefined ? {} : { dataId: id }), data: jsonInput(options.input) })
+    }
+  }
+
+  if (command === 'table' && ['read', 'write'].includes(subcommand)) {
+    const table = required(rest[0], 'TABLE', `Run: giz table ${subcommand} TABLE_PATH --input JSON`)
+    return {
+      kind: 'result',
+      value: await invoke(baseUrl, subcommand === 'read' ? 'table.readRows' : 'table.writeRows', {
+        ...jsonInput(options.input),
+        table,
+        ...(options.computer ? { computer: options.computer } : {})
+      })
+    }
+  }
+
   if (command === 'upload') {
     const localFile = required(subcommand, 'LOCAL_PATH', 'Run: giz upload ./reference.png')
     return { kind: 'result', value: await uploadMedia(baseUrl, localFile) }
@@ -552,38 +698,33 @@ async function runCommand(baseUrl, positionals, options) {
     throw new CliError(`Unknown computer command "${subcommand || ''}".`, 'Run: giz computer --help')
   }
 
-  if (command === 'site') {
+  if (command === 'app') {
     const computer = options.computer ? { computer: options.computer } : {}
     if (subcommand === 'list') {
-      return { kind: 'result', value: await invoke(baseUrl, 'site.list', computer) }
+      return { kind: 'result', value: await invoke(baseUrl, 'app.list', computer) }
     }
-    if (subcommand === 'create' || subcommand === 'update') {
+    if (subcommand === 'save' || subcommand === 'create') {
       const input = jsonInput(options.input)
-      const siteId = subcommand === 'update'
-        ? required(rest[0], 'SITE', 'Run: giz site update SITE --input JSON')
-        : undefined
-      return {
-        kind: 'result',
-        value: await invoke(baseUrl, 'site.configure', {
-          ...input,
-          ...computer,
-          operation: subcommand,
-          ...(siteId ? { siteId } : {})
-        })
-      }
+      return { kind: 'result', value: await invoke(baseUrl, 'app.save', { ...input, ...computer }) }
     }
-    if (subcommand === 'verify') {
-      const siteId = required(rest[0], 'SITE', 'Run: giz site verify SITE')
-      return {
-        kind: 'result',
-        value: await invoke(baseUrl, 'site.configure', { ...computer, operation: 'verify', siteId })
-      }
+    if (subcommand === 'run') {
+      const id = required(rest[0], 'APP_ID', 'Run: giz app run APP_ID --expected-revision REVISION')
+      return { kind: 'result', value: await invoke(baseUrl, 'app.run', { ...computer, id, expectedRevision: appRevision(options) }) }
+    }
+    if (subcommand === 'publish') {
+      const id = required(rest[0], 'APP_ID', 'Run: giz app publish APP_ID private|workspace|public')
+      const visibility = required(rest[1] || options.visibility, 'VISIBILITY', 'Run: giz app publish APP_ID private|workspace|public')
+      return { kind: 'result', value: await invoke(baseUrl, 'app.publish', { ...computer, id, visibility, expectedRevision: appRevision(options) }) }
+    }
+    if (subcommand === 'open') {
+      const id = required(rest[0], 'APP_ID', 'Run: giz app open APP_ID')
+      return { kind: 'result', value: await invoke(baseUrl, 'app.open', { ...computer, id }) }
     }
     if (subcommand === 'delete') {
-      const siteId = required(rest[0], 'SITE', 'Run: giz site delete SITE')
-      return { kind: 'result', value: await invoke(baseUrl, 'site.delete', { ...computer, siteId }) }
+      const id = required(rest[0], 'APP_ID', 'Run: giz app delete APP_ID')
+      return { kind: 'result', value: await invoke(baseUrl, 'app.delete', { ...computer, id, expectedRevision: appRevision(options) }) }
     }
-    throw new CliError(`Unknown site command "${subcommand || ''}".`, 'Run: giz site --help')
+    throw new CliError(`Unknown app command "${subcommand || ''}".`, 'Run: giz app --help')
   }
 
   if (command === 'capability') {
@@ -722,6 +863,10 @@ function print(kind, value, json, output = process.stdout) {
     output.write(`${value}\n`)
     return
   }
+  if (kind === 'auth' && value.identity?.type === 'computer') {
+    output.write(`컴퓨터 신원으로 로그인됨 (소유자 ${value.email || value.name})\n`)
+    return
+  }
   if (kind === 'models') {
     const rows = value.models || []
     for (const model of rows) output.write(`${model.id}\t${model.type}\t${model.provider || '-'}\t${model.label}\n`)
@@ -752,12 +897,22 @@ function print(kind, value, json, output = process.stdout) {
 }
 
 function help(command) {
+  if (command === 'engine') return `Usage
+  giz engine run claude "instruction" [--dir path]
+
+Runs the official Claude Code in an isolated worktree. Connect Claude Code in Giz first.
+Progress and the final diff, files and summary are returned. Interrupting stops the engine.`
   if (command === 'api-key') return `Usage
   giz api-key list
   giz api-key create "My app" [--scopes giz.inference,giz.read] [--expires ISO_TIMESTAMP]
   giz api-key revoke KEY_ID
 
 The secret is shown only when the key is created.`
+  if (command === 'credits') return `Usage
+  giz credits
+
+Prints your remaining credit (purchased and plan), when plan credit resets, and this month's spend and charges.
+In a workspace it prints the workspace's monthly budget. Read it before paid batch work.`
   if (command === 'chat') return `Usage
   giz chat MODEL "your prompt"
   giz chat MODEL --input '{"messages":[{"role":"user","content":"Hello"}]}'`
@@ -766,17 +921,24 @@ The secret is shown only when the key is created.`
   giz model get MODEL
   giz model run MODEL --input JSON [--upload FIELD=LOCAL_PATH]
 
-Run model get first. Its live input schema is the source of truth. Repeat --upload for multiple media inputs.`
+Run model get first. Its live input schema is the source of truth. Repeat --upload for multiple media inputs.
+model run returns a job immediately. Retrieve the result with giz job wait JOB_ID, or poll with giz job get JOB_ID.
+For speech-to-text, use model run with the audio field returned by model get. Callback/webhook delivery is not supported.`
   if (command === 'generate') return `Usage
-  giz generate image|video|audio|music|talking-head "PROMPT" [--model MODEL]
+  giz generate image|video|music|talking-head "PROMPT" [--model MODEL]
+  giz generate audio --input '{"purpose":"speech","script":"Hello"}' [--model MODEL]
+  giz generate audio --input '{"purpose":"sound","prompt":"Rain","duration":5}'
 
 Options
   --image LOCAL_PATH       Upload a visual reference
   --audio LOCAL_PATH       Upload speech audio
   --upload FIELD=PATH      Upload into an exact tool field
-  --input JSON             Additional generation parameters`
+  --input JSON             Input matching the tool schema (@FILE reads a file, - reads stdin)
+
+For model-specific audio options, inspect giz model get MODEL and pass supported fields in settings (for example settings.speed), not at the top level.
+Generation returns a job immediately; use giz job wait JOB_ID for its result.`
   if (command === 'drive') return `Usage
-  giz drive list [PATH]
+  giz drive ls [PATH]  (list alias)
   giz drive search QUERY
   giz drive read PATH
   giz drive write PATH --content TEXT
@@ -784,16 +946,30 @@ Options
   giz drive mkdir PATH
   giz drive move FROM TO
   giz drive delete PATH`
+  if (command === 'table') return `Usage
+  giz table list
+  giz table get TABLE
+  giz table read TABLE [--input JSON] [--computer COMPUTER]
+  giz table write TABLE --input JSON [--computer COMPUTER]
+  giz table action TABLE ACTION [--id ID[,ID...]] --input JSON
+
+TABLE is a table's Drive path (for example Sales/Customers.view.ts) or a business object name from giz table list
+(for example task, issue, requirement). giz table get shows its fields, the row changes it accepts (writes) and its
+actions; an object without a write changes only through its actions. Use --org to work in an organization.
+read input:  {"select":["name"],"filters":[{"field":"status","operator":"eq","value":"open"}],"limit":50}
+write input: {"create":[{"name":"Acme"}],"update":[{"id":"ROW_ID","status":"done"}],"remove":["ROW_ID"]}
+One write is one change people can undo in the table. At most 200 rows per write.`
   if (command === 'computer') return `Usage
   giz computer list
   giz computer get|start|stop [COMPUTER]
   giz computer exec [--computer COMPUTER] [--cwd PATH] [--deadline-ms MS] [--stdin TEXT|--stdin-file PATH] -- COMMAND [ARGS...]`
-  if (command === 'site') return `Usage
-  giz site list [--computer COMPUTER]
-  giz site create [--computer COMPUTER] --input JSON
-  giz site update SITE [--computer COMPUTER] --input JSON
-  giz site verify SITE [--computer COMPUTER]
-  giz site delete SITE [--computer COMPUTER]`
+  if (command === 'app') return `Usage
+  giz app list [--computer COMPUTER]
+  giz app create|save [--computer COMPUTER] --input JSON
+  giz app run APP_ID --expected-revision REVISION [--computer COMPUTER]
+  giz app publish APP_ID private|workspace|public --expected-revision REVISION [--computer COMPUTER]
+  giz app open APP_ID [--computer COMPUTER]
+  giz app delete APP_ID --expected-revision REVISION [--computer COMPUTER]`
   if (command === 'capability') return `Usage
   giz capability list [--computer COMPUTER]
   giz capability search skill|mcp QUERY
@@ -812,26 +988,30 @@ Options
 stdio (default) shares giz auth login and refreshes tokens automatically.
 http uses the client's own OAuth login. Install the chosen client first.`
   if (command === 'auth') return `Usage
-  giz auth login
+  giz auth login [--device]
   giz auth status
   giz auth logout`
   return `Giz CLI — AI models, Drive, and Computer from any terminal
 
 Usage
-  giz auth login
+  giz auth login [--device]
   giz api-key list|create|revoke
   giz chat MODEL "your prompt"
   giz model list [--type TYPE] [--search TEXT]
   giz model get MODEL
   giz model run MODEL --input JSON [--upload FIELD=LOCAL_PATH]
-  giz generate image|video|audio|music "PROMPT" [--model MODEL]
+  giz generate image|video|music|talking-head "PROMPT" [--model MODEL]
+  giz generate audio --input JSON [--model MODEL]
   giz job list|get|wait|cancel [JOB]
-  giz drive list|search|read|write|mkdir|move|delete
+  giz credits
+  giz drive ls|list|search|read|write|mkdir|move|delete
+  giz table list|get|read|write|action
   giz upload LOCAL_PATH
   giz computer list|get|start|stop|exec
-  giz site list|create|update|verify|delete
+  giz app list|create|save|run|publish|open|delete
   giz capability list|search|install|update|remove
   giz agent start|status|cancel
+  giz engine run claude "instruction" [--dir path]
   giz mcp url|serve|check|add
   giz skill install
   giz invoke TOOL --input JSON
@@ -841,6 +1021,7 @@ Use giz COMMAND --help for parameters and examples.
 Global options
   --json                 Machine-readable JSON output
   --base-url URL         Another Giz deployment
+  --org ORGANIZATION     Organization id to work in (or GIZ_ORGANIZATION)
   --no-open              Print the login URL without opening a browser
 
 Docs: https://www.giz.ai/mcp/`
@@ -849,7 +1030,12 @@ Docs: https://www.giz.ai/mcp/`
 async function main() {
   const { positionals, options } = parse(process.argv.slice(2))
   const saved = await readConfig()
-  const baseUrl = String(options['base-url'] || process.env.GIZ_URL || saved?.baseUrl || DEFAULT_URL).replace(/\/+$/, '')
+  const requiresAuth = positionals.length && !options.help && !options.version &&
+    !(positionals[0] === 'auth' && ['login', 'logout'].includes(positionals[1]))
+  const computer = requiresAuth && !process.env.GIZ_TOKEN && !saved?.access_token ? await computerIdentity() : undefined
+  const baseUrl = String(options['base-url'] || process.env.GIZ_URL || saved?.baseUrl || computer?.baseUrl || DEFAULT_URL).replace(/\/+$/, '')
+  if (typeof options.org === 'string') process.env.GIZ_ORGANIZATION = options.org
+  options.input = await inputText(options.input)
   const output = await runCommand(baseUrl, positionals, options)
   if (output) {
     print(output.kind, output.value, options.json === true)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gizai/cli",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Giz CLI, MCP installer, OpenAI-compatible models, Drive, and Computer",
   "type": "module",
   "bin": {
@@ -31,8 +31,8 @@
   "homepage": "https://www.giz.ai/mcp/",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/exinno/giz.git",
-    "directory": "apps/space/external"
+    "url": "git+https://github.com/GizAI/giz.git",
+    "directory": "apps/giz/external"
   },
   "publishConfig": {
     "access": "public"

package/skills/giz/SKILL.md

@@ -36,7 +36,7 @@ giz model run MODEL_ID --input '{"prompt":"..."}'
 Use the OpenAI-compatible chat boundary:
 
 ```bash
-giz chat gpt-5-6-luna "..."
+giz chat gpt-6-luna "..."
 ```
 
 Upload local media into an exact model field:
@@ -63,3 +63,63 @@ Pass `--json` for machine output. Use `GIZ_TOKEN` only in ephemeral automation.
 - Do not retry failed generations blindly. Report the provider or contract error.
 
 Read [references/operations.md](references/operations.md) when MCP discovery is unavailable or when choosing between Drive and Computer tools.
+
+App 변경은 `giz app list`에서 확인한 `revision`을 명시적으로 전달합니다.
+`run`, `publish`, `delete`에는 `--expected-revision REVISION`이 필요합니다.
+`create`/`save`의 `--input`에는 `id`와 `expectedRevision`을 넣습니다(새 앱은 0).
+목록을 다시 읽어 개정 번호를 자동 대체하지 않으므로, 검토 뒤 다른 변경이 생기면 서버가 충돌을 거부합니다.
+
+아래 표는 CLI 디스패처와 도구 item에서 생성합니다. 갱신 명령:
+`GIZ_UPDATE_CLI_SURFACE=1 pnpm --filter giz-app-giz test --runInBand --runTestsByPath server/external/cli-surface.spec.ts`.
+일반 CI 실행은 문서를 쓰지 않고 표의 차이를 실패로 보고합니다.
+
+<!-- cli-surface:start -->
+| CLI 명령 | 도구 ID | MCP 이름 | 필수 입력 | scope | Agent 발견 |
+| --- | --- | --- | --- | --- | --- |
+| model list | model.list | model_list | - | giz.read | model.list |
+| model get | model.get | model_get | model | giz.read | model.get |
+| model run | model.run | model_run | model, input | giz.inference | model.run |
+| generate image | generateImage | generateImage | prompt | giz.write | generateImage |
+| generate video | generateVideo | generateVideo | prompt | giz.write | generateVideo |
+| generate music | generateMusic | generateMusic | prompt | giz.write | generateMusic |
+| generate talking-head | generateTalkingHead | generateTalkingHead | prompt, references | giz.write | generateTalkingHead |
+| generate audio | generateAudio | generateAudio | purpose | giz.write | generateAudio |
+| job list | job.list | job_list | - | giz.read | server job |
+| job get | job.get | job_get | job | giz.read | server job |
+| job wait | job.get | job_get | job | giz.read | server job |
+| job cancel | job.cancel | job_cancel | job | giz.destructive | server job |
+| credits | account.credits | account_credits | - | giz.read | account.credits |
+| drive ls | drive.list | drive_list | - | giz.read | drive.list |
+| drive list | drive.list | drive_list | - | giz.read | drive.list |
+| drive search | drive.search | drive_search | query | giz.read | drive.search |
+| drive read | drive.readFile | drive_readFile | path | giz.read | drive.readFile |
+| drive write | drive.writeFile | drive_writeFile | path, content | giz.write | drive.writeFile |
+| drive mkdir | drive.makeDirectory | drive_makeDirectory | path | giz.write | drive.makeDirectory |
+| drive move | drive.movePath | drive_movePath | from, to | giz.write | drive.movePath |
+| drive delete | drive.deletePath | drive_deletePath | path | giz.destructive | drive.deletePath |
+| table list | workspace.objects | workspace_objects | - | giz.read | workspace.objects |
+| table get | workspace.objects | workspace_objects | - | giz.read | workspace.objects |
+| table read | table.readRows | table_readRows | table | giz.read | table.readRows |
+| table write | table.writeRows | table_writeRows | table | giz.write | table.writeRows |
+| table action | workspace.executeAction | workspace_executeAction | view, action | giz.execute | workspace.executeAction |
+| computer list | computer.list | computer_list | - | giz.read | computer.list |
+| computer get | computer.get | computer_get | - | giz.read | external only |
+| computer start | computer.start | computer_start | - | giz.execute | external only |
+| computer stop | computer.stop | computer_stop | - | giz.destructive | external only |
+| computer exec | computer.exec | giz_computer_exec | - | giz.execute | computer.exec |
+| app list | app.list | app_list | - | giz.read | app.list |
+| app create | app.save | app_save | id, expectedRevision | giz.execute | app.save |
+| app save | app.save | app_save | id, expectedRevision | giz.execute | app.save |
+| app run | app.run | app_run | id, expectedRevision | giz.execute | app.run |
+| app publish | app.publish | app_publish | id, expectedRevision, visibility | giz.write | app.publish |
+| app open | app.open | app_open | id | giz.read | app.open |
+| app delete | app.delete | app_delete | id, expectedRevision | giz.destructive | app.delete |
+| capability list | capability.status | capability_status | - | giz.read | capability.status |
+| capability search | capability.catalog | capability_catalog | kind, query | giz.read | capability.catalog |
+| capability install | capability.install | capability_install | id, kind, query | giz.execute | capability.install |
+| capability update | capability.manage | capability_manage | id, operation | giz.destructive | capability.manage |
+| capability remove | capability.manage | capability_manage | id, operation | giz.destructive | capability.manage |
+| agent start | agent.start | agent_start | agentId, prompt | giz.execute | external only |
+| agent status | agent.status | agent_status | turnId | giz.read | agent.status |
+| agent cancel | agent.cancel | agent_cancel | turnId | giz.execute | agent.cancel |
+<!-- cli-surface:end -->

package/skills/giz/references/operations.md

@@ -8,6 +8,9 @@
 | List, search, or read Drive | `drive_list`, `drive_search`, `drive_readFile` |
 | Create or change Drive content | `drive_writeFile`, `drive_makeDirectory`, `drive_movePath`, `drive_importUrl` |
 | Move Drive content to Trash | `drive_deletePath` |
+| Read a table's fields and rows | `table_readRows` |
+| Create, update or remove table rows (one undoable change per call) | `table_writeRows` |
+| Turn rows into a new table | `table_createFromRows` |
 | Discover and control Computers | `computer_list`, `computer_start`, `computer_stop` |
 | Run a Computer command | `giz_computer_exec` |
 | Find, inspect, or interact with an existing terminal | `terminal_list`, `terminal_observe`, `terminal_send` |

package/skills/giz/references/slides.md

@@ -0,0 +1,95 @@
+# Giz Presentation & Slide Authoring
+
+The requested deliverable is a presentation: editable PPTX and, when requested,
+PDF. Choose the design workflow from the user's intent. Image-designed proposals
+start with complete slide images; direct SVG authoring remains an option.
+`slides.create/read/edit/inspect/export` share one Drive document for reconstruction
+and subsequent edits. The SVG is an intermediate representation and live preview;
+it must not dictate or simplify the image model's design.
+
+## Image-designed proposals
+
+1. Read the source material and reference pages. Establish the audience, narrative,
+   approved wording, numbers and sources. Retain this content separately from image
+   recognition: generated pixels do not override approved facts.
+2. Discover the requested image model with `model.list/model.get`. Use its actual
+   quality, size and reference-image contract. Honor the requested model; report a
+   failure instead of silently substituting the default or a cheaper model. Use
+   `model.run` with the exact retrieved input schema for model-specific quality or
+   variant controls, including subsequent reference-image cleanup.
+3. Generate **complete slide designs**, including typography, headings, body copy,
+   diagrams, cards and artwork, through the existing image generation tools. Match
+   the reference's visual ambition, information density and aspect ratio. Pass reference images
+   to maintain composition and consistent design across pages. Save the finished
+   slide images in Drive; they are the visual targets for conversion.
+4. Inspect each target at readable resolution. Inventory all visible components,
+   including icons and decorative marks, before cleanup; account for every one in
+   the reconstructed layers. Reconstruct its actual composition,
+   text bounds, line breaks, hierarchy, colors, borders and grouping in reference
+   pixel coordinates. Do not redesign it as a generic template. Native text uses
+   the approved source wording even where the image misspells or changes a number.
+5. Extract photographs, logos and complex artwork with `assets` pixel crops.
+   Where editable labels overlap artwork, edit the original image through
+   the same image model and quality settings with that reference. Remove only the
+   labels and preserve the composition. Inspect the cleaned pixels for leftover glyphs and unwanted design
+   changes. Cropping alone does not clean text; flat masks cannot restore complex
+   backgrounds. Rebuild simple cards, lines, arrows and labels as native objects.
+   If retaining a background layer, remove those editable objects from its pixels
+   too: moving a card or text box must not leave its original raster version behind.
+6. Compose the reconstructed layers in one SVG document. Match the actual reference
+   dimensions on every page, preserve stable object IDs and logical `g` groups,
+   and use visible `text`/`tspan` with explicit line baselines and page fonts.
+   Do not outline glyphs or use invisible text over full-slide screenshots.
+   Preserve notes/citations and the original design image Drive path in each page's
+   `desc` so future edits can repeat the same reference comparison. Match the
+   reference typography and geometry; do not shrink body copy merely to hide an incorrect reconstruction.
+7. Run `slides.inspect` with `previewPages` and corresponding `referenceImages`.
+   This renders the deck once through PPTX and LibreOffice and returns each
+   original image beside its exported counterpart in the observation sequence.
+   Compare composition, artwork, typography, line breaks, content and cleanliness.
+   `info.export.textBounds` gives measured rendered lines in SVG coordinates;
+   use them to correct placement through `slides.read/edit`, then inspect again.
+   The technical `passed` flag does not measure similarity to the reference.
+8. Export the exact inspected revision with `slides.export`. Deliver the PPTX/PDF,
+   retain the original design images and editable source, and disclose raster-only
+   areas or unresolved differences. LibreOffice rendering does not establish pixel
+   identity in Microsoft PowerPoint.
+
+## Direct SVG authoring
+
+When direct vector authoring suits the request, create native text, shapes, groups
+and optional artwork directly, then use the same inspection and export path.
+This option does not replace a requested image-model design workflow. The live
+SVG editor and PowerPoint use different text renderers.
+
+## Canonical source and asset placement
+
+```json
+{
+  "path": "Proposals/inventory.svg",
+  "content": "<svg xmlns=\"http://www.w3.org/2000/svg\" id=\"deck\" viewBox=\"0 0 1920 1080\"><svg data-slide=\"true\" id=\"slide-1\" viewBox=\"0 0 1920 1080\"><title>Inventory</title><rect width=\"1920\" height=\"1080\" fill=\"#FFFFFF\"/><image id=\"hero\" x=\"1000\" y=\"100\" width=\"800\" height=\"600\"/><g id=\"value\"><rect x=\"80\" y=\"160\" width=\"840\" height=\"320\" rx=\"16\" fill=\"#EEF4FA\"/><text id=\"headline\" x=\"120\" y=\"250\" font-family=\"Noto Sans CJK KR\" font-size=\"48\" fill=\"#123456\">재고를 한눈에 확인</text></g></svg></svg>",
+  "assets": {
+    "hero": { "path": "Proposals/artwork.png", "crop": { "left": 620, "top": 70, "width": 800, "height": 600 } }
+  }
+}
+```
+
+Asset paths are relative to the Drive root. A plain string embeds the whole image;
+`{path,crop}` extracts exact pixels after EXIF orientation, without resizing.
+SVG geometry controls placement. Out-of-bounds crops fail before saving. The same
+asset map works for creation and element edits; an existing image requires its
+replacement fingerprint. Embedded bytes make the saved document self-contained.
+
+`slides.read` returns a compact outline. Selected text/shapes return exact XML and
+opaque `before` values. Images and groups containing images return attributes and
+`imageIds` instead of embedded bytes. Use `changes:[{id,before,attributes:{x:"80"}}]`
+to change geometry without resending content; `null` removes an attribute. Use
+`attributes:{}` together with `assets` to replace artwork. Attribute changes and
+`after` XML replacements are mutually exclusive and share the same fingerprint/CAS.
+Read individual child IDs when changing the contents of a group. Insert a page under the root with `slides.edit.inserts`; preserve
+unrelated objects. Whole-document replacement requires `expectedRevision`.
+
+Inspection example: `slides.inspect({path:"Proposals/inventory.svg", expectedRevision,
+previewPages:[1], referenceImages:[{page:1,path:"Proposals/design-1.png"}], language:"ko-KR"})`. Export requires `path`, `expectedRevision`, `format` (`pptx` or
+`pdf`) and a new `outputPath`. Set `language:"ko-KR"` for Korean. `reversePages`
+changes export page order only when requested for the actual printing workflow.