# Publishing a book

> Write a book's public page with a skill you can swap, keep your own writing beside it, and undo any run.

A shared shelf can give each book its own page, not only a card. **Publish this book…** asks a skill, through Model Hub, to write that page: what the book is, who wrote it, and where to buy it from the author's own pages. You see the result before anything is written.

## Before you start

- Model Hub 0.12 or later, with a model that can search the web for the `library-hub.publish` role.
- A share template that shares notes to a folder. Pages go in its `summaries` folder; with no `summaries` block they go in a `Book Summaries` folder beside the notes folder, and the review says so ([Sharing shelves](sharing.md)).

## Steps

1. Open a book note. In the **Library** panel, on the **Book** tab, select **Publish page**. (Or run **This book: Publish this book…**; for every book on a shelf, open the shelf note and select **Publish all books** on the **Shelf** tab.)
2. The row shows *Asking the model…* with the time. It costs a few cents a book. A shelf run stops at the amount in **Settings → Sharing → Publishing a book**, and the books it did not reach stay without a row; run it again for the rest.
3. When it says *Ready to review*, read the page text, the buy links it kept, and any it dropped because their address did not answer. If it says *Failed*, the reason and what to do are in the row, and nothing was written.
4. Select **Write the page** (**Write all** on a shelf). Select **Undo** under **Activity** on the Library tab, or run **Sync: Undo a notes sync**, to take it back.

## Your text and the skill's

A summary note has two zones.

- **Yours** is everything outside `<!-- publish-book:start -->` and `<!-- publish-book:end -->`: the intro at the top, and any sections you add. Publishing never edits it.
- **The skill's** is the text between those marks. Publishing again replaces only that, and the preview tells you when it will.

You never have to run the skill. A summary note with no marked block is simply your own page.

## Private notes

When the skill returns a critique, it goes to `_Reading notes.md` in the book's own folder, never to the page. The leading underscore keeps your site from reading it. A reading-notes note that already holds your writing is never overwritten.

## What the page can hold

- At most three quotes, each at most 25 words. A page over the limit is not written.
- Buy links are fetched once. A link that is gone (404 or 410), whose server fails, or that does not answer is dropped. A shop that turns a robot away still counts as answering.
- The last line says whether the page was written from the book's own text or from public sources.
- The page is **unpublished** unless the share template says `publish: true` under `summaries`, or you set `published: true` yourself.

## Use your own skill

Library Hub ships a skill called `publish-book`. To use another, add a skill in your Model Hub skills folder and put its name in **Settings → Sharing → Publish skill**. A skill of the same name in your folder replaces the shipped one.

A skill replies with one JSON object:

```json
{ "body": "markdown", "buy": [{ "kind": "book", "label": "US", "url": "https://…" }], "sources": ["https://…"], "basis": "public sources", "critique": "optional" }
```

`kind` is `book` or `audiobook`; every address starts with `http://` or `https://`. Anything else is refused and nothing is written.

## Where the questions come from

The shipped skill asks for what a careful reader would: what the whole book is about in a sentence, how it is built, the questions the author set out to answer, and the terms used in a special sense. They adapt the reading questions in the study-skills project, which in turn adapt Adler and Van Doren and Booth. Library Hub does not include or need study-skills.

## What it sends

The brief a skill gets holds the book's title, authors, year, ISBN, publisher, formats, context line, shelf name, and the one-page summary already in your book note if there is one. It goes to the model you set up in Model Hub, which may search the web. Checking buy links sends a request to each address. Nothing else from your vault is sent.
