# Create a Toshokann Library or Archive

A derivative starts with the complete Toshokann application: the generalized BOSS library browser, librarian chat, profile/provider controls, first-run catalog import, DBOPFS file manager, and full backup/restore workflow. Customize those capabilities through one extension. Do not rebuild a smaller parallel application or copy the runtime into a branded fork.

## Choose the collection policy

Library and Archive are policy profiles over the same runtime:

| Profile | Primary goal | Catalog approach | Revision policy |
| --- | --- | --- | --- |
| Library | Make current working knowledge discoverable | Categories, resource types, organizations, topics, audiences, and useful synonyms | A maintained record may be replaced intentionally in a new catalog version. |
| Archive | Describe and retrieve retained snapshots | Stable collection, record-type, date, creator, rights, and provenance descriptions | Give each edition a stable identity; add a record for a new edition and retain prior bytes when preservation matters. |

Toshokann retrieval does not itself create legal custody, authenticity, retention, WORM storage, preservation certification, or compliance. Those controls belong to the derivative's governance and infrastructure.

## 1. Create the derivative repository

Fork or clone the authorized Toshokann source, then give the new repository and package their real identity. Keep Toshokann as an upstream remote if you intend to receive neutral runtime fixes.

Create the extension from the empty reference:

```powershell
Copy-Item -LiteralPath .\extensions\empty -Destination .\extensions\example-library -Recurse
New-Item -ItemType Directory -Path .\extensions\example-library\documents
```

Use a lowercase, hyphen-delimited application ID consistently in the extension, manifest, package metadata, and every application's `<meta name="arcane-app-id">` declaration.

## 2. Define product policy, not replacement mechanics

Edit `extensions/example-library/extension.js`:

```js
import { defineExtension } from '../../src/core/extension.js';

export default defineExtension({
  schemaVersion: 1,
  id: 'example-library',
  displayName: 'Example Library',
  description: 'Find the maintained knowledge for Example.',
  catalogUrl: './extensions/example-library/catalog.json',
  emptyState: {
    title: 'No documents available',
    message: 'Add approved records to this collection.',
  },
  facets: [],
  navigation: [],
  appearance: {
    tokens: {
      'app-accent': 'rgb(38, 78, 61)'
    }
  },
  library: {
    seedPrefix: 'example-library--',
    manifestVersionKey: '.example-library-manifest-version.json',
    refreshEvent: 'example-library-documents-refreshed',
    synonymGroups: [
      ['finding aid', 'collection guide']
    ]
  },
  assistant: {
    enabled: true
  }
});
```

Point `src/active-extension.js` at this extension. The extension owns identity, catalog location, managed seed namespace, terminology, prompt, provider adapters, model aliases, support route, and other product policy. Toshokann continues to own DBOPFS, import/inspection, raw Markdown storage, search/ranking, bounded context, chat, profile, file management, and backup/restore.

For an existing BOSS migration, the extension may retain its established managed prefix, manifest marker, refresh event, catalog record aliases, domain synonyms, prompt, and provider/model policy. That compatibility is why these values are extension inputs rather than renamed core constants.

## 3. Add the catalog and Markdown holdings

Place published Markdown under the extension, for example:

```text
extensions/
`-- example-library/
    |-- catalog.json
    |-- extension.js
    `-- documents/
        `-- getting-started.md
```

A canonical new catalog can use:

```json
{
  "schemaVersion": 1,
  "version": "2026-08-13",
  "documents": [
    {
      "id": "getting-started",
      "title": "Getting Started",
      "name": "getting-started.md",
      "path": "documents/getting-started.md",
      "summary": "A concise guide to the approved workflow.",
      "tags": ["onboarding"],
      "categories": ["operations"],
      "resourceTypes": ["guide"],
      "access": "public"
    }
  ]
}
```

The adapter also retains the established BOSS manifest aliases so existing holdings do not need a destructive schema rewrite. Use safe relative paths and accurate access/sensitivity metadata. Treat all fetched Markdown as untrusted data.

On first run, Toshokann inspects `documents`, computes the managed filenames for the active manifest, and imports missing packaged Markdown in bounded batches. It writes a completion/version marker only for a nonempty successful seed. Later refreshes reuse correct managed files, import missing ones, remove only stale files within the extension's managed prefix, and leave user-uploaded Markdown unchanged.

Do not place private originals, working notes, credentials, source-only conversion files, or anything else below a recursively packaged extension directory unless it is intended for recipients.

## 4. Rebrand the application surfaces

Update the derivative-owned values in:

- `manifest.webmanifest` and `arcane-package.json`;
- extension identity and active-extension selection;
- application title/description fallbacks and `arcane-app-id` declarations;
- navigation identity, approved logo or text mark, support route, and palette;
- librarian prompt, tool descriptions, synonyms, provider/model policy, and regulated-domain limits;
- README, header art, repository URLs, license notices, and Pages documentation.

Do not change shared table names, DBOPFS APIs, seed/inspection behavior, search/context mechanics, chat contracts, profile tuple structure, or backup format merely to rebrand the product.

## 5. Package the full runtime

Toshokann's own `toshokann.package.json` intentionally publishes only the documentation site. A runnable derivative needs a separate positive allowlist containing at least:

- `app.html`, `library.html`, `library-setup.html`, `profile.html`, `export.html`, and `import.html`;
- `manifest.webmanifest` and the derivative's package descriptor;
- `src`, `components`, `prompts`, and exactly one selected extension;
- the complete vendored `arcane` browser runtime and `node_modules/strong-type` notice/runtime;
- the applicable license and source-offer material;
- only the derivative assets and holdings approved for release.

The repository's `arcane-package.json` records the neutral runtime surface for Arcane packaging. A standalone derivative may adapt `tools/build.mjs` to a distinct runtime manifest, but must not replace the docs-only allowlist accidentally or publish both unreviewed trees under one receipt.

## 6. Verify the derivative

Add tests that prove:

1. the active extension and application ID agree;
2. the manifest loads and every packaged Markdown path resolves;
3. empty and nonempty first-run behavior are correct;
4. seed refresh touches only the derivative's managed prefix and marker;
5. user Markdown remains visible and survives a managed refresh;
6. search, access filters, preview, bounded context, chat, profile, import/export, and file-manager links work;
7. the public artifact contains no other extension, private holding, credential, or source-only file;
8. product branding and policy appear only in the selected extension and derivative-owned surfaces;
9. the deployed revision offers the source and notices required by its license.

Run:

```powershell
npm run check
```

For protected deployments, also test the exact origin/profile isolation, CSP and dependency policy, identity and access controls, encryption/key custody, audit, backup/restore, retention/deletion, incident response, and release approvals required by the collection. DBOPFS alone is not those controls; see [`security.md`](security.md).