Use the library

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."

This page takes an entry into a project you already have. A new service that keeps its data in the database starts with Build a database-backed service. That page's first step is one line. It writes the service and takes, copies, and installs the Database package for it.

What your tool does

  • Reads the platform's add-library-entry skill, which sets the order of the steps below.
  • Calls list_library, which needs no account, and chooses the smallest entry whose summary fits the capability you asked for, reading its package page's Use it when section first. Where more than one fits, it asks you which. Where none fits, it tells you rather than working around a package's contract, and it presents a package the library does not serve as unserved.
  • Calls read_library_entry with the entry's name. The response includes the line that takes the entry with the turnzero-cloud command, in a form for macOS and Linux and a form for Windows (step 3).
  • Runs the line for its operating system at your project's root. The line checks every file against its listed SHA-256 before it writes anything. It then writes the entry's row in system/manifest.json and the entry's files under system/ (step 3).
  • For a package with compiled code, the same line copies the code into app/lib/<name>/, declares @turnzero/<name> as file:lib/<name> in app/package.json, and runs npm install (step 5).
  • Records the version in the project's instance file, where the project keeps one, and regenerates the manifest's packages member (step 7).
  • Verifies the take (step 4), commits what the line wrote, and edits nothing in the library folder afterwards. A needed improvement is recorded in your own project.
  • Later, when you ask for updates, reads the update-library skill and asks you once per entry before updating it (step 6).
  • Asks for no browser approval: the two library actions only read, and every write is to your project.

What you need

  • A project of your own, one your 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).
  • For a package with compiled code, your application's package.json, at app/package.json or at the project's root. Without one, the line refuses and writes nothing. It says to make the package.json first. For a package that a scaffold template takes, in a project with no app/ folder or an empty one, it also gives that template's scaffold line, which writes a new service with its package.json. The Database package gives the database-service line, and the Schedule package the scheduled-job line.

Before your AI starts

This section is for your AI tool: what it checks and gathers before it begins. You don't need to do these steps yourself.

  • The two library actions need no account.
  • Where the project uses Turn Zero Blueprint, its registrar connected. The registrar is Blueprint's tool server, and its validate with kind library verifies a take. Without it, list_library with installed verifies the take instead.

Steps

1. Read what is published

Turn Zero Cloud offers the latest published library. list_library 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. An entry you name in installed, described in step 4, is always listed. Only what it lists can be taken, even where other documentation describes a version or capability that the library does not list.

read_library_entry with an entry's name returns its file list, with each file's hash and size. Add file to read one listed path. Check the response's encoding: write utf8 content as UTF-8 bytes, and decode base64 content before writing and hashing.

Read a large file in chunks. Add limit, up to 16000 code points, then pass each response's next_offset as offset with its stamp until next_offset is null. Join the chunks' content in order, decode it where the encoding is base64, and check the result against the listed hash. If a publication changes the file between two chunks, the platform refuses the stale stamp with context_changed; start again at offset 0 without a stamp.

Each publication replaces the current library, and older versions are not kept. read_library_entry takes no version: it reads the version list_library lists. 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 three documents: 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 beside it. The folder contains the JavaScript modules, their TypeScript declarations, and an index.js that re-exports every module except the test double module. The package.json names the package @turnzero/<name> at the package's version. The entry contains no TypeScript source and no tests. Nine packages include code: Account, AI Allowance, Database, Egress, Issue Tracking, Logging, Push, Schedule, and Storage. The platform loads the Node.js Runtime package's module before your code, so its entry contains only documents.

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

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.

One entry, library/prd, of kind document, contains the library's own requirements: feature_packages.md, which defines the package format, and platform.md, the platform contract. The package documents cite requirements in these two files. Where list_library lists the entry, take it with your first entry and read a cited requirement there. Where it does not, the current library does not include it.

This entry has no version and no summary. Most publications change it, and it is compared by content hash alone, so list_library often reports it newer. Taking it again is optional, because nothing depends on its version. In a Turn Zero Blueprint project, keeping the entry reserves the requirement prefixes FTR and PLAT. A project that numbers its own requirements under either prefix does not take the entry, and reads those requirements from the published library.

3. Add an entry to the library folder

The add-library-entry skill takes an entry with one line, which runs the turnzero-cloud command's library take. Through the Model Context Protocol (MCP), read_library_entry with only name returns download, which contains the line in two forms. download.command is the line for macOS and Linux. download.command_windows is the same line for Windows, with npx.cmd in place of npx. download.next says what remains after the line.

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

npx -y https://turnzero.ai/packages/turnzero-cloud-<version>.tgz library take --entry database

The response gives the line with the command's version in place of <version>. Where your tool is connected to an origin other than https://turnzero.ai, the line also includes --origin with that origin, so you set nothing yourself. Your tool runs the form for its operating system as the response gives it, at your project's root. That is the folder that contains system/ or system.json beside app/, or, on a first take, the folder where the new system/ is made.

The line reads every listed file and checks each one's SHA-256 and the entry's closure hash. It writes nothing until every file is checked. It then writes the entry's row in system/manifest.json and each listed file at system/<path>, where <path> is the file's path in the listing. The entry's own path, which read_library_entry also returns, gives the folder the files are written to:

  • system/features/<name>/ for a package;
  • system/ui/<name>/ for a vocabulary;
  • system/ui/assets/fonts/<family>/ for a font;
  • system/prd/ for the library's own requirements.

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

Four rules apply together for a package with code. Fetch the entry into system/, copy its package.json and lib/ into app/lib/<name>/, and declare it in app/package.json as file:lib/<name>. Leave system/ out of the deploy zip, which includes app/lib/ instead (Build and upload the artifact). The line follows the first three for you, as step 5 describes.

The line writes every row and every file itself, so your tool writes none by hand. A row or a file written by hand can differ from what the library published, and a check of the folder then reports the entry as moved.

system/manifest.json records one row per entry, with the members name, version, closure_hash, source_commit, and fetched_at. The closure_hash is the hash of the entry's whole closure, every listed file with its path, as the library catalog contract states. The version of a font and of the requirements entry is null.

Keep every entry whole. A project that uses only a package's runtime module still keeps every file the entry lists: the documents ship beside the code and do nothing at run time. A folder missing any listed file no longer hashes to its row's closure_hash, so a check of the folder reports the entry's bytes as moved. Keep the copy unchanged, and record a needed improvement in your own project instead.

A Turn Zero Blueprint project keeps an instance file for each feature package it uses, under requirements/app_features/, and the file pins the package's version. Record the version there, and the manifest row in its Exact Package and Dependency References section. A project without Turn Zero Blueprint has no instance file; system/manifest.json already records the version.

4. Check the download

With the Turn Zero Blueprint registrar connected, validate with kind library hashes the local files and compares them with the manifest. An older registrar reports the library/prd row as unaddressable, in validate, status, and library alike. Update Turn Zero Blueprint, or check that row with list_library and installed.

Without the registrar, the line has already checked each file against its published hash before it wrote it. Then call list_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 the entries listed in installed, which are all the check needs. The response gives each entry a standing:

  • current: the recorded hash equals the published hash. This confirms the take.
  • newer: a publication happened after the take. 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. Nothing was compared, and you need not install it. A call with held_only returns no such entry, and a call with contains returns only those its text matches.

This call compares recorded hashes with the published library. It does not read your local files, so only validate finds a hand edit of a taken file. Treat the folder as read-only.

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 system/features/<name>/lib/ into app/lib/<name>/. On a first take it declares the dependency in app/package.json as a path, never a registry name. No test checks this sample.

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

The line then runs npm install in app/, which links the copy into node_modules, and prints installed:. 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, whose package.json is at the root, the line uses lib/<name>/ and the root package.json in place of app/lib/<name>/ and app/package.json, and runs npm install at the root.

Where the install fails, the line ends with status 1, and the entry, its row, and the copy stay 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'. That name resolves to lib/index.js, which re-exports the package's modules. The application's tests import the test double from the testing subpath, as step 2 describes. The application installs no compiler and compiles nothing.

Include app/lib/ in the deploy artifact, or lib/ in a project with no app/ folder. The platform never builds your code: its image build runs npm install over your artifact's package.json and lockfile, which links the copied package with your other dependencies.

The modules are ES modules; an application in CommonJS scope loads them with import(). The Account package's declarations import types from Node's built-in modules, so an application that type-checks against them installs @types/node.

6. Take a newer version

The update-library skill compares the hash of each entry your project keeps with the published library through list_library with installed, and asks you before updating each entry. For each entry you accept, it:

  1. runs the entry's line from step 3 again, which rewrites the entry's manifest row, replaces its folder whole, and, for a package with code, replaces the copy in app/lib/<name>/ and runs npm install;
  2. reads the package's Lifecycle, Migration, and Removal entries above the version you have, and follows them;
  3. moves the version pin in the project's instance file;
  4. regenerates the packages member (step 7);
  5. verifies the update as step 4 describes.

7. Copy the rows into the manifest member

At each submission, your tool copies each row of system/manifest.json into the application manifest's packages member, as the row's name and version and nothing else. The platform reads only the manifest you submit and never reads system/manifest.json. A deploy compares the packages rows with the zip's lib/ copies, and its manifest_notice lists a copy the rows do not match (Build and upload the artifact). Keep no second list of packages by hand; the admission manifest contract states the rule. Then submit the manifest as Author the manifest describes.

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

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

Each package's page, such as Database, describes the package for a reader. Where versions differ, list_library is correct.

Expected result

list_library returns entries, each with name, kind, version, closure_hash, and summary, and source_commit and published_at for the publication. With installed, it also returns a standing on every entry, one of the four values in step 4. With held_only beside installed, it returns only the entries listed in installed. With contains, it returns only the entries whose name or summary contains that text, and every entry listed in installed.

read_library_entry returns entry with files, each a path, a sha256, and a size. Through MCP, it also returns download, with the line in command and command_windows and the steps after it in next. With file, it returns file with path, encoding, content, and sha256, and a chunk also includes stamp, offset, total, and next_offset.

The line prints a taken: line and, for a package with code, a copied: line and an installed: line. Its packages: line gives the rows step 7 copies, and it ends with status 0.

After the take, 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.

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

Refusals

A refusal identifies the action, states the cause in its detail, and writes nothing. A standing of newer, withdrawn, or not_held is a normal result, not a refusal; step 4 says what each means. Refusals lists every refusal the platform returns. The line's own refusals and statuses are on The turnzero-cloud command.

Refusal Status Cause Remedy
invalid_request 400 read_library_entry was called without name, or with offset, limit, or stamp and no file. Or list_library was called with held_only and no installed, or with a contains that is not text or is over 200 characters. Give the entry's name as list_library returns it, and the file a chunk reads. Pass installed beside held_only, or leave held_only out. Pass 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_entry named an entry the published library does not include, or a file not in the entry's file list. Take the name from list_library and the path from the file list, then call again. A withdrawn entry stays usable from your project's copy.