Use the library #

View this page as Markdown

On this page

Prompt:

This app stores users' documents. Use whatever the platform already provides rather than building it from scratch.

Also works:

  • "Is there a ready-made way to do sign-in here, or do I write it?"
  • "Bring the storage package into this project."
  • "Are the packages we use out of date? Bring them up to date."

Your AI tool finds an entry with read_library (step 1) and takes it into your project with one line, such as turnzero library take --entry database (step 3). For a package with code, the line also copies it into app/lib/<name>/, and the application installs it from there (step 5).

This page adds an entry to a project you already have. To start a new service that keeps its data in the database, use Build a database-backed service instead. Its first step is one line that writes the service and takes the Database package for it. That package is optional, since any PostgreSQL driver reaches the database.

The notes app is a template that turnzero scaffold --template notes-app writes, not a library entry.

Downloading an entry requires a credential. Before running turnzero library take, authorize this computer or supply a minted token. Signing your AI tool in to MCP does not authorize the CLI. An AI tool without a shell can read the entry's files over its signed-in MCP connection instead (step 1).

What your AI tool does #

  • Reads the add-library-entry skill (read_context, id skill:add-library-entry) and follows it.
  • Reads the chosen package's page, starting with its Use it when section. Where no entry fits, it tells you so, rather than using a package in a way its contract does not allow.
  • Later, when you ask for updates, reads the update-library skill (read_context, id skill:update-library) and follows it.
  • Asks you which entry to take where more than one fits. Before an update, it asks you once for each entry. It needs no approval in the browser: the library action only reads, and every write goes to your project.

What you need #

  • A project of your own, one your AI tool can write to and save changes in.
  • Node.js 24 or later, and npm, on your computer, which run the line and install a package's code (What your computer needs).
  • A token for the CLI: this computer's, set up as Authorize this computer for deploys shows, or a minted token your AI tool sets for the line.
  • For a package with compiled code, your application's package.json, at app/package.json or at the project's root. Where neither file exists, the line makes a minimal app/package.json and goes on. It refuses instead where the root holds a src/ folder or a source file such as server.mjs: add that code's package.json at the root first.

You can prepare your application's files before signing in. For an ES-module app whose server is app/server.mjs, app/package.json can start as:

{
  "name": "my-app",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node server.mjs"
  }
}

Keep an existing app's scripts and dependencies. This example has no Turn Zero dependency because no package has been downloaded yet. Leave out file:lib/... dependencies while the files they point to are missing.

Once the command is authorized, run library take from the project root, the folder containing app/. It copies the package, adds its file: dependency and runs npm install (step 3). For an app kept at the project root, use its existing root package.json instead.

Before your AI starts #

For the AI tool: Check the following before starting.

  • The library action runs under your account's credential. The library take command reads this computer's token, which login keeps, or a minted token. Without a token, the line sends nothing.
  • Where the project uses Turn Zero Team (tzTeam), its registrar connected. The registrar is tzTeam's tool server, and its validate with kind library verifies the downloaded entry. Without it, read_library with installed verifies the downloaded entry instead.

Steps #

1. Read what is published #

read_library without entry lists every entry with its name, kind, version, content hash, and summary. To find one entry, add contains, such as "contains": "storage". The response then lists only the entries whose name or summary contains that text, ignoring case. Where no entry contains it and held_only is not set, the response's note lists every entry the library serves, so a word the library does not use still shows what is there. An entry you name in installed, described in step 4, is always listed. Only what it lists can be taken.

read_library with entry set to an entry's name returns its file list, with each file's hash and size. Add file to read one listed path; a large file comes in chunks. A tool with no shell can read each file this way, over MCP, signed in.

Each publication replaces the current library, and older versions are not kept. read_library takes no version: it reads the library's current publication. With entry and history: true, its previous_versions gives each earlier version's number and dates, never its files. Your project keeps its committed copy, so a newer publication changes nothing your project contains or has deployed.

2. Know what an entry contains #

The entry of a feature package contains its product statement prd.md, its detailed contract <name>.md, and its integration guide integration.md. A package with runtime code also contains that code as an npm package, a lib/ folder and a package.json named @turnzero/<name>. Eleven packages include code: Account, AI Allowance, Database, Egress, Email, Issue Tracking, Logging, Push, Schedule, Storage, and Turn Zero Mesh.

No @turnzero package is published to the npm registry. Download each package only from the library with the library take command.

Each of those eleven packages also ships a test double at its testing subpath, @turnzero/<name>/testing, which only the application's tests import. The two other packages ship none: the platform loads the Node.js Runtime package's code itself, and the Secrets package has no client module.

A vocabulary's entry contains its documents and, for the style system, its sheets and its resolver. A font family's entry contains its font files and license. The entry library/prd holds the library's own requirements, which the package documents cite. The add-library-entry skill says when to take it.

3. Add an entry to the library folder #

Without a shell, your AI tool can have Cloud fill a supported runtime package from the manifest's packages and root file: dependency, with no copy in deploy_files.

The add-library-entry skill takes an entry with one line, which runs the turnzero command's library take. Through the Model Context Protocol (MCP), read_library with only entry returns download, which contains the line in four forms. download.command is the line for macOS and Linux. download.command_windows is the same line for Windows, with turnzero.cmd in place of turnzero. Your AI tool first runs download.command_npx, or download.command_npx_windows on Windows. These use npx and need no global turnzero installation. download.next says what remains after the line. Where download.next says no line takes the entry, the command cannot take it.

No MCP action writes an entry into your project, since a remote server cannot write your AI tool's files. Taking an entry needs a shell that reaches the platform. Where your AI tool's shell cannot reach it, your AI tool asks you to run the line in your own terminal, at your project's root.

For the Database package, the line for macOS and Linux has this form:

turnzero library take --entry database

This example shows download.command, which runs the installed version. The npx forms name turnzero@latest instead. Every form prints the version it runs before taking the entry.

If your AI tool is connected to a platform other than https://turnzero.ai, the returned command includes --origin with that platform's address. You do not need to set the address yourself.

Your AI tool first runs download.command_npx, or download.command_npx_windows on Windows, exactly as returned, at your project's root. That is the folder that contains system/ or system.json beside app/, or, on the first download, the folder where the new system/ is made.

The line reads this computer's token, which login keeps, or the minted token your AI tool sets for the line, as the deploy line does.

For example, taking Database into an application with app/package.json and no Database dependency writes these two entries. The rows show an example version; the command writes the version the library publishes.

File Member Entry added or updated
app/package.json dependencies "@turnzero/database": "file:lib/database"
app/manifest.json packages {"name": "database", "version": "0.15.0"}

The dependency uses @turnzero/<name> and a path relative to the folder that holds package.json; each packages row is the entry's name and version.

Step 5 shows the copied files and the paths for a project whose package.json is at the root. Step 7 explains which manifest the platform reads and when to submit it.

Without a global installation: With Node.js and npm installed, you can run npx --no-update-notifier -y turnzero@latest library take --entry database from the project root. Use the returned download.command_npx or Windows form for your chosen entry, keeping its options. It uses the same credential as the installed command.

Unattended jobs: A script or CI job running without an AI coding tool can run the npx line, npx --no-update-notifier -y turnzero@latest library take --entry <name>, instead of installing the command. Run it from the project's root with Node.js 24 or later and npm. Set TURNZERO_CLOUD_MINTED_TOKEN from the job's secret store, as Deploying unattended describes; no interactive login is needed. The command downloads and writes the whole entry.

For the AI tool: Try download.command_npx first, or download.command_npx_windows on Windows. It works whether or not turnzero is installed globally. If npx can't run here, use the installed form when turnzero --version responds. Otherwise, try installing the command.

If npm install -g turnzero can't run here, use another available route to add the entry to your project. If none works, give the person the exact step you cannot run. A person or a job may use any of the four forms.

For a chat deploying without local package copies, follow Deploy from a chat. Cloud can fill supported runtime feature packages from the submitted manifest; it does not create a local library folder or download arbitrary entries.

Keep the entry whole #

The library folder is the project's own system/. A project without one can keep a system.json file at its root that names a shared folder instead, such as one at the repository's root. The folder it names must exist and lie inside the repository, or the line refuses and writes nothing.

Where the folder holds neither system/ nor system.json, but the folder above it holds one, the line refuses and writes nothing. The folder may be an application's folder inside that project. Run it in the folder above or, where the folder is a project of its own, make an empty system/ folder in it and run the line again.

The line reads every listed file and checks each one's SHA-256 and the entry's closure hash. The closure hash is one SHA-256 for all the entry's files, so a changed, added or removed file changes it.

It writes nothing until every file is checked. It then writes the entry's row in the library folder's manifest.json and each listed file under that folder: under features/<name>/ for a package, ui/<name>/ for a vocabulary, and ui/assets/fonts/<family>/ for a font. Where a read returns HTTP 502, 503, or 504, the line tries it again after 2, then 4, then 8 seconds, at most three more times.

Where a check fails, the line writes nothing and ends with status 3. Run it again to take the entry whole. The turnzero command reference gives each status of library take.

The command refuses, with nothing written, a library folder, an entry's folder, a copy, or the application manifest that is reached through a link leading outside your project. The command also refuses a symbolic link or junction at any path it writes, whatever the link points to. The paths it writes are the library folder's manifest.json, the manifest.json.partial beside it and beside the application manifest, and the package.json it adds the declaration to. They also include the .take staging names in the library folder and beside the copy.

If the application manifest is a broken symbolic link or junction, the command refuses and writes nothing.

Four rules apply together for a package with code. Fetch the entry into the library folder, copy its package.json and its lib/ folder, kept as a folder, into app/lib/<name>/, and declare it in app/package.json as file:lib/<name>. Deploy from app/, so the zip holds lib/ at its root and leaves system/ out. In a project with no app/ folder, the zip includes system/ beside lib/, and the image build installs from the copies in lib/, never from system/ (The two project layouts). The line follows the first three for you, as step 5 describes.

The line writes every row and every file itself, so your AI tool writes none by hand. Keep every entry whole and unchanged, its documents included. A folder that is missing a listed file, or has changed one, no longer matches its row, and a check reports the entry as moved since the fetch. A tzTeam project also records the version in the package's instance file.

Removing a package entry is the exception: your AI tool deletes its row in the library folder's manifest.json and its features/<name>/ folder together by hand (Author the manifest). In a tzTeam project, first read the package's integration guide for what removal does to its instance file. A package's removal may require deleting that file or recording consequences in it.

4. Check the download #

With the tzTeam registrar connected, validate with kind library hashes the local files and compares them with the manifest.

Without it, call read_library with installed, one item per manifest row: its name, its version, and its closure_hash passed as hash. Add held_only: true to return only those entries. The response gives each entry a standing:

  • current: the recorded hash equals the published hash. This confirms the recorded download.
  • newer: a publication happened after the download. Run the entry's line again, which takes it whole and rewrites its row.
  • withdrawn: the published library no longer includes the entry. The project keeps using its copy.
  • not_held: the published library includes an entry your project has not taken.

This call compares recorded hashes and reads no local file, so only validate finds a hand edit of a taken file.

5. Install a package's compiled code #

The application installs the package from its own copy. For a package with compiled code, the line from step 3 copies system/features/<name>/package.json and the system/features/<name>/lib/ folder into app/lib/<name>/. On the first download it declares the dependency in app/package.json as a path, never a registry name.

"dependencies": {
  "@turnzero/database": "file:lib/database"
}

The copy keeps the entry's lib/ as a folder: app/lib/<name>/package.json beside app/lib/<name>/lib/, not the files of lib/ loose in app/lib/<name>/. The package's own package.json points its name at lib/index.js inside the copy, and Node.js finds the package only there, so the copy is laid out like this:

app/
├── package.json
└── lib/
    └── <name>/
        ├── package.json
        └── lib/
            ├── index.js
            └── the rest of the entry's lib/ files

The line then runs npm install in app/, which links the copy into node_modules. Never write there yourself. After an install that ends with status 0, the command reads node_modules/@turnzero/<name>/package.json through the link.

If that file cannot be read, the command runs npm install --install-links once in the same folder and reads again. It prints installed: only after a successful install leaves the file readable. If the second install fails or the file remains unreadable, the line ends with status 1; the entry, its row, and the copy stay written. Run the library take command again to download the whole entry. A failed first install starts no second install.

Where your project already declares the copy at another file: path, the line replaces the copy at that path and leaves the declaration as it is. Commit the copy, app/package.json, and its lockfile beside your code. In a project with no app/ folder and a package.json at its root, the line uses lib/<name>/ and that root package.json. Where the package.json is at the project's root and the project also has an app/ folder, the copy is app/lib/<name>/, declared file:app/lib/<name>.

Where neither place has a package.json, the line makes app/package.json with only what the install needs. That is "private": true, a name made from your project folder's name, "type": "module" where the package's own package.json declares it, and the dependency, with no scripts. It prints one made: line that says so, and goes on as above. To start a whole new service instead, the scaffold line writes the application and takes the entry. npm install receives neither TURNZERO_CLOUD_MINTED_TOKEN nor TURNZERO_CLOUD_UPLOAD_GRANT.

The line prints one line after its reading: line and before it writes, saying the application goes in app/ and why. Where the root holds a src/ folder or a source file such as server.mjs and no package.json, it refuses and writes nothing. It names what it found and the two ways on: add the package.json at the root, or move that code into app/.

If you downloaded a package before scaffolding, scaffold refuses the nonempty app/ folder and gives recovery commands. Check that the folder contains only generated files before deleting it. Then scaffold and download any packages the template does not include.

Where the install fails, the line ends with status 1, and the entry, its row, and the copy stay written. It ends the same way where the application manifest's packages member could not be written. Run npm install in app/, or run the line again. In Windows PowerShell, run npm as What your computer needs describes.

Import the package by the name in its package.json, for example import { applyMigrations } from '@turnzero/database', and the test double from the testing subpath. The modules are ES modules. An application in CommonJS scope loads them with import(). The Account package's type declarations import Node.js types, so an application that checks its types installs @types/node.

After taking and installing Account, a CommonJS file, account-client.cjs, can load its client like this:

async function createAccountClient(options) {
  const { makeVerifyClient } = await import('@turnzero/account');
  return makeVerifyClient(options);
}

module.exports = { createAccountClient };

Call await createAccountClient(options) from an async function. The Account client lists the options, including the required baseUrl.

Put the copy in a deploy #

After taking the package, keep its copy and the file: dependency together. For Account in an app/ project, app/package.json declares "@turnzero/account": "file:lib/account". The copy holds app/lib/account/package.json beside app/lib/account/lib/, including its compiled files. Submit the application manifest with the package's name and version before deploying (step 7).

Choose the route you are using:

  • The turnzero command: run turnzero deploy from the folder containing the application's package.json, normally app/. The command includes the copy under lib/account/. Keep that path out of .deployignore; turnzero hash --list lets you check the files the zip will hold.
  • A file list with deploy_files: send the copy's files, or omit the whole copy so the platform can fill it. To fill it, the list's top package.json must declare the file: dependency, and the submitted manifest's packages row must name account at the version the library currently serves. List no path at or under the copy's declared path. If you send any part of the copy, send all its files: the platform fills none of that copy. Keep your local copy committed even when you omit it from this deploy.
  • A zip for the upload route: include the copy yourself; this route does not fill it. With package.json at the zip's root, the Account copy is lib/account/package.json beside lib/account/lib/. Zip the contents of app/, not the app/ folder around them. Deploy from your computer gives the upload steps.

A library copy Cloud fills needs no entry in package-lock.json; without a shell, write no lockfile for it. Send a lockfile npm already wrote unchanged.

Other packages use their own entry name in place of account. For a project with no app/ folder, deploy from the root containing package.json and lib/; the zip includes its system/ folder too. The image build installs from the declared copies, never from system/ (The two project layouts).

6. Take a newer version #

The update-library skill compares each entry your project keeps with the published library through read_library with installed, and asks you before updating each one. For each entry you accept, it runs the entry's line from step 3 again, which replaces the entry whole and, for a package with code, its copy. It then opens features/<name>/<name>.md in the project's library folder (normally system/). It follows that document's Lifecycle, Migration, and Removal section's entries above your old version, moves the instance file's pin, and checks the update as step 4 describes.

7. The rows in the manifest member #

The application manifest is app/manifest.json where app/ holds package.json, as in a scaffolded project, and otherwise manifest.json beside a package.json at the project's root. Where it exists, the library take line rewrites its packages member from the rows of system/manifest.json after each download. Each entry holds the row's name and version and nothing else, and the line's packages: line says it wrote them.

If the manifest does not exist, the command creates a minimal manifest with the package rows, no services, and a public audience. Add the services and audience your application needs before submitting it.

The command rewrites the whole manifest as two-space JSON, so read it again before editing. Preserve packages when changing other fields, then submit the updated manifest before deploying.

The platform uses the submitted manifest, not system/manifest.json. A deploy reports mismatches between packages and the ZIP's library copies in manifest_notice. Without a folder manifest, enter the packages names and versions by hand from read_library; deploy_files checks them against the served library when filling omitted runtime packages. Deploy from a chat gives that route.

A row of system/manifest.json, and the entry of packages copied from it:

system/manifest.json  {"name": "database", "version": "0.15.0", "closure_hash": "…", "source_commit": "…", "fetched_at": "…"}
manifest packages     {"name": "database", "version": "0.15.0"}

Expected result #

The line first prints a reading: line naming the entry, its version, and its count of files. Where it makes app/package.json, the line saying the application goes in app/ comes next.

The command prints taken: and, for a package with code, copied: and installed:. It prints made: if it created app/package.json. The packages: line reports the manifest update or tells you to copy the rows if it could not write them. A successful run exits with status 0. After the download, the project contains:

  • the entry's files under system/features/<name>/;
  • its row in system/manifest.json;
  • for a package with code, app/lib/<name>/, with the file: dependency declared and linked into node_modules;
  • where none existed, the application manifest, made with the rows and the other members of the smallest manifest.

validate with kind library finds the folder equal to its manifest, or read_library with installed returns current for the row. Your AI tool reports the entry, its version, the files it wrote, and the import name.

Refusals #

See the refusals reference for other platform errors.

A standing of newer, withdrawn, or not_held is a normal result, not a refusal. The line's own statuses are on the turnzero command reference.

Refusal Status Cause Remedy
invalid_request 400 file, offset, limit, stamp, or history was given without entry; entry was empty or not text; or an entry read included installed, held_only, or contains. Give entry for an entry read. Leave it out for an inventory read, which alone accepts installed, held_only, and contains.
invalid_request 400 An entry read gave offset, limit, or stamp without file, or a history value other than true or false. Give a listed file path with chunk arguments. Give history as true or false, or leave it out.
invalid_request 400 An inventory read gave held_only: true without installed, a non-boolean held_only, or a contains that is not text or is over 200 characters. Pass installed beside held_only: true. Give held_only as true or false, and contains as a short piece of text.
context_changed 409 A publication changed the file between two chunks of one read. Read the file again from offset 0 without a stamp.
no_such_entry 404 read_library named an entry the published library does not include, or a file not in the entry's file list. Take the name from read_library and the path from the file list, then call again; where the refusal gives the entry's path for your file, use that. A withdrawn entry stays usable from your project's copy.
  • Each package's page, such as Account, describes the package for a reader. Where versions differ, read_library is correct.
  • The manifest describes the packages member step 7 fills.
  • The turnzero command describes library take, which the line runs.
  • read_library gives the action's arguments and result.