@apprun/shiqu 0.6.5 → 0.7.0

package/NOTICE

@@ -17,6 +17,9 @@ upstream contributors are credited in the catalog and original downloads.
 Project Gutenberg downloads retain their own accompanying notices and terms.
 
 Third-party dependency license texts and notices remain applicable. The
+CLI offline exporter bundles Noto Sans CJK SC under the SIL Open Font License;
+see data/export-fonts/OFL.txt and data/export-fonts/README.md.
+The
 Standard desktop edition also includes the Node.js distribution's LICENSE
 alongside the bundled Node executable.
 

package/README.md

@@ -2,13 +2,14 @@
 
 Turn Chinese classics into your own illustrated storybooks. Read in your browser, generate with a logged-in Codex CLI, OpenAI API, or Gemini, and keep stories, images, and reading progress on your computer.
 
-## CLI or desktop app?
+## Choose how to use Shiqu
 
-**Choose the desktop app for everyday use; choose the CLI if you already have Node 24, prefer a terminal, or need scripted startup.**
+**Choose the desktop app for graphical use, the Codex skill to delegate tasks in natural language, or the CLI for direct commands and scripted startup.**
 
 | Your situation | Recommended entry point |
 | --- | --- |
 | You want graphical settings, library and queue management, and no separate Node installation | Desktop app: includes Node 24 and service controls |
+| You want Codex to create, edit, export, or maintain stories without a server | Install the Shiqu skill and invoke `$shiqu`; requires Node 24 |
 | You already have Node 24 and want one-command startup without installing a desktop app | CLI: `npx @apprun/shiqu`; keep the terminal running and press Ctrl+C to stop |
 | You want generation and reading access to continue after closing the control window | Desktop app: stays in the system tray until you stop the service or quit the app |
 | You need startup parameters, environment overrides, or non-interactive operation | CLI: prepare provider configuration and a library path in advance |
@@ -16,7 +17,7 @@ Turn Chinese classics into your own illustrated storybooks. Read in your browser
 | You want phone access on the same Wi-Fi | Both entries: CLI prints phone QR codes on startup; desktop shows them in its control window |
 | You need built-in internet tunnel controls | Desktop app: requires a separate cloudflared installation. CLI has no built-in internet tunnel |
 
-**Shared features:** Both entry points provide the same browser interface for story creation, production and acceptance requirements, generation queues, pause/resume, reading, library organization, and PDF / PNG / ZIP export. The desktop window adds library, queue, settings, and service controls; full reading and story creation happen in the browser. Both support OpenAI API, Gemini, and read-only mode. Codex generation is supported on macOS / Linux and requires a separately installed, logged-in Codex CLI; the Shiqu CLI and Codex CLI are different tools.
+**Shared features:** Both entry points provide the same browser interface for story creation, production and acceptance requirements, generation queues, pause/resume, reading, library organization, and PDF / PNG / ZIP export. The desktop window adds library, queue, settings, and service controls; interactive reading and story creation happen in the browser. The Codex skill uses CLI subcommands for production, editing, library maintenance, and offline exports without a running service. Both support OpenAI API, Gemini, and read-only mode. Codex generation is supported on macOS / Linux and requires a separately installed, logged-in Codex CLI; the Shiqu CLI and Codex CLI are different tools.
 
 **Shared settings and data:** Under the same local user account, both entry points reuse saved provider settings and API keys. With the same library directory, they share stories, images, and reading progress. Neither requires the other to be running.
 
@@ -28,6 +29,62 @@ Turn Chinese classics into your own illustrated storybooks. Read in your browser
 
 **Only one service can run against a library at a time, even on different ports.** Switching entry points needs no data copy. Choosing another directory opens another library; it does not move or merge data. Back up before upgrading or downgrading, as older versions may not read newer settings or data. See the [full user guide](https://github.com/yysun/shiqu/blob/main/.docs/user-guide.md).
 
+## Use Shiqu through Codex
+
+Install the bundled skill once, then ask Codex to perform Shiqu tasks in natural language. The skill defines data contracts, business rules, and acceptance criteria. Codex can write task-specific programs for filtering, comparison, reports, and batch orchestration; saved-state changes, generation, review, and exports use Shiqu's existing production implementation.
+
+See the [prompt-only Use as SKILL guide](https://github.com/yysun/shiqu/blob/main/.docs/use-as-skill.md) for copyable requests covering setup, provider/model configuration, creation and editing, exports, batch tasks, recovery, and diagnostics.
+
+```bash
+npx @apprun/shiqu skill install --scope global
+```
+
+Global installation copies the skill to `~/.agents/skills/shiqu/SKILL.md` for use across projects. For one project, run `skill install --scope project` in that directory; it writes `.agents/skills/shiqu/SKILL.md` there. Both scopes copy independent files, reject symlinks and different existing instructions, and require an explicit scope. Installing a skill does not start a server, initialize or move a library, or globally install the CLI executable.
+
+In Codex, invoke the skill with a request such as:
+
+```text
+$shiqu Find a story about kindness and misunderstanding in Zhuangzi.
+Use Chinese ink painting and balanced narrative detail. Show candidates and a production plan first;
+wait for my confirmation before generating illustrations, then export an offline preview and public ZIP.
+```
+
+Specify the library, output directory, and author credit in your request. Codex queries the selected CLI version's help and chooses operations from saved state. Simple tasks can call the CLI directly; generated programs use argument arrays and JSON input without modifying SQLite or reimplementing generation or exports. Shiqu uses its saved generation provider and credentials. Library commands automatically create the directory and initialize the database on first access using the same startup/migration path as desktop and server; no separate init step is required. Configure a provider first if needed. Stop any service using the same library before running headless commands. Only explicit run performs inference; edits, inspection, preview and export do not start background generation.
+
+`skill show` prints the instructions without installing them. If a new skill does not appear in Codex, restart Codex. The copied skill does not pin the CLI runtime: use `npx @apprun/shiqu@VERSION` when a fixed version is required. Use `skill check` to report npm release updates (cached for 24 hours), `skill check --auto-update on|off` to save your preference, and a fixed-version `skill update --scope global|project` to copy that CLI package’s bundled skill. Automatic updates are off by default: Codex applies the returned pinned command only after opt-in, without overriding explicit or project-pinned versions. Installation state records version and content hash; local edits, unknown copies, unsupported state and downgrades are refused. Legacy copies can be registered by reinstalling their matching package only when their contents match. Offline checks retain the existing version. No background updater is installed.
+
+### Direct headless commands
+
+With no subcommand, Shiqu starts the existing browser service. Subcommands operate directly on the production workflow without HTTP, desktop, or frontend:
+
+```bash
+npx @apprun/shiqu help --json
+npx @apprun/shiqu stories list --data-dir /private/shiqu-library
+npx @apprun/shiqu run STORY_ID --until reviewed --data-dir /private/shiqu-library
+npx @apprun/shiqu preview STORY_ID --data-dir /private/shiqu-library --output /private/preview.html
+npx @apprun/shiqu export STORY_ID --data-dir /private/shiqu-library --format zip --output /private/story.zip
+npx @apprun/shiqu skill show
+```
+
+Use `help --json` for command inputs and effects. Subcommands return one JSON receipt on stdout, logs on stderr, and nonzero exit codes on errors. The exception is skill show, which prints Markdown unless --json is supplied. Only explicit run invokes inference, only for the specified story. Saving, editing, confirmation, inspection and export do not start background generation. Read reason/session before continuing; pauses/faults require explicit control/recovery. Intake mutations require explicit `--generation N` or input.generation from stories get. Retry/override require explicit faultId. Reuse the same request UUID and original generation/token/faultId and input for mutation replay; edits require the token from `stories revisions ID`.
+
+Creation follows create → search → run until candidates → choose → run until prepared → confirm → run until reviewed or completed. Follow returned IDs and states. Complete ZIP/PDF/PNG exports require the current version and all images. Public ZIP is the default; internal prompts require `--include-prompts`. Unsigned export requires `--allow-unsigned`. Preview is escaped, self-contained HTML. Outputs must be new paths. Config reuses saved settings; keys go through input files/stdin, never argv.
+
+`init` remains optional for explicit early initialization. Database creation follows --data-dir, SHIQU_DATA_DIR, saved location, then the default library; it does not configure a provider or start generation. Corrupt databases fail instead of being rebuilt. Backup requires an existing database. Help, catalogs, skill installation and diagnostic export do not create a library; restore still requires a new target directory.
+
+To choose a database folder explicitly:
+
+```bash
+npx @apprun/shiqu init --data-dir /absolute/path/my-library
+npx @apprun/shiqu stories list --data-dir /absolute/path/my-library
+```
+
+The argument is a directory: Shiqu creates it if needed and stores `shiqu.sqlite` and `media/` there. Existing data is retained. The command returns the resolved absolute path. This does not change the saved desktop/CLI default; reuse --data-dir or set SHIQU_DATA_DIR for later commands.
+
+### Library maintenance
+
+Maintenance is shared with desktop libraries: `shiqu --backup <new-directory>`, `shiqu --verify-backup <backup>`, `shiqu --restore <backup> --data-dir <new-library>`, and `shiqu --diagnostics <new-json-file>`. Stop all services before backup; diagnostics can be exported while running. Restore never overwrites an existing directory or starts generation. Backups include private story/media data, not the separate provider credentials. Existing libraries receive a verified sibling `library-backups/pre-upgrade-*` snapshot before new migrations; keep these private and restore with a matching application version. Diagnostic exports contain bounded allowlisted metadata, not prompts, keys, story text or raw provider responses.
+
 ## Run
 
 Requires **Node 24** (recommended: 24.22.1) and its bundled npm / npx. No separate pnpm installation is needed:

package/data/export-fonts/OFL.txt

@@ -0,0 +1,92 @@
+This Font Software is licensed under the SIL Open Font License,
+Version 1.1.
+
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font
+creation efforts of academic and linguistic communities, and to
+provide a free and open framework in which fonts may be shared and
+improved in partnership with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply to
+any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software
+components as distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to,
+deleting, or substituting -- in part or in whole -- any of the
+components of the Original Version, by changing formats or by porting
+the Font Software to a new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed,
+modify, redistribute, and sell modified and unmodified copies of the
+Font Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components, in
+Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the
+corresponding Copyright Holder. This restriction only applies to the
+primary font name as presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created using
+the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/data/export-fonts/README.md

@@ -0,0 +1,8 @@
+# Offline export font
+
+`NotoSansCJKsc-Regular.otf` is the Noto CJK Simplified Chinese regular font from
+https://github.com/notofonts/noto-cjk/tree/main/Sans/OTF/SimplifiedChinese.
+Its SIL Open Font License is retained in `OFL.txt`.
+
+The CLI registers this bundled font for Chinese export text so offline ZIP watermarks,
+PDF and PNG do not depend on an operating system's installed CJK fonts.