# PSCOT Writing Library — v1.0.0

PSCOT is a framework-free PHP and SQLite website for presenting books, novellas, short stories, articles, and other written work by Jay Pscot. Uploaded documents and front/back covers remain outside the public web directory and are served only through controlled PHP routes.

## Requirements

- PHP 8.2 or newer
- PDO SQLite (`pdo_sqlite`)
- Fileinfo (`fileinfo`)
- JSON
- Apache with `.htaccess` support, or equivalent server rules
- HTTPS for production

PSCOT has no Composer, PHP framework, JavaScript framework, CSS framework, Node, build system, database server, or third-party analytics dependency.

## Expected host layout

```text
~/sites/pscot.com/             Public website files from this package
~/data/pscot.com/              Private persistent data
    pscot.sqlite3              SQLite database
    documents/                 Uploaded document files
    covers/                    Uploaded front- and back-cover images
    backups/                   Backup snapshots
    config.php                 Optional local overrides
```

The application normally infers `~/data/pscot.com` from `~/sites/pscot.com`. Set `PSCOT_DATA_ROOT` for both web and CLI PHP when another private-data path is required.

## Upgrade from v0.1.9

1. Back up `~/data/pscot.com/`.
2. Copy the v1.0.0 package over the existing v0.1.9 public site.
3. Do **not** rerun the installer.
4. Open PSCOT normally.
5. Sign in at `/desk/` and complete the deployment checks below.

v1.0.0 has no database schema changes. Existing catalog entries, documents, covers, authors, tags, prepared views, permissions, analytics, and settings remain intact.

The former `/admin/` route remains redirected to `/desk/` by `.htaccess`.

## Public footer and software license

The public footer links to Privacy, Terms, and License pages and displays the current PSCOT version.

The PSCOT application source code is released under the MIT License. The license applies to the PHP, JavaScript, CSS, database schema, and supporting application source code. It does **not** apply to books, articles, stories, uploaded documents, cover artwork, logos, branding, or other catalog content unless that material is separately identified as licensed.

The package includes `LICENSE-v1.0.0.txt`, and the public `/license.php` page presents the same terms.

## Librarian interface

The administrative interface uses library terminology:

- **Librarian** instead of Administrator
- **Circulation Desk** instead of Dashboard
- **Catalog** instead of Documents
- `/desk/` instead of `/admin/`

The Desk navigation is: Circulation Desk, Catalog, Authors, Tags, Views, Settings.

The Desk footer displays version and copyright information on the left and the same compact mark-plus-PSCOT treatment used in the public footer on the right.

## Supported document formats

Documents may be uploaded as:

```text
PDF, EPUB, TXT, Markdown, HTML, RTF, DOC, DOCX, ODT
```

Recognized HTML extensions are `.html` and `.htm`. Upload validation checks both the filename extension and a reasonable content MIME type. Uploaded files remain under `~/data/pscot.com/documents/`, not inside the public site.

Documents are limited to 50 MB by default. Front and back covers may be JPEG, PNG, or WebP and are limited to 5 MB each. Preserve the supplied `.htaccess` upload limits:

```apache
php_value upload_max_filesize 64M
php_value post_max_size 64M
```

## Read, Preview, and Download

Publication and file permissions remain independent:

- `is_published` controls whether a catalog entry appears publicly.
- **Allow Read** exposes an inline public action.
- **Allow Download** exposes the complete original file as a download.
- Amazon may be present independently of either file permission.

Partial Preview from 1–99 percent is permitted only for:

```text
.txt .md .markdown .html .htm
```

PDF, EPUB, RTF, DOC, DOCX, and ODT are forced to 100 percent whenever Read is enabled. This restriction is enforced by the editor, server-side save path, automatic database migration, and reader route.

Public wording is:

- `100%` — **Read**
- `1–99%` — **Preview**

Download always sends the complete original file when enabled.

## Percentage calculation

PSCOT caps a partial Preview by stored bytes:

```text
bytes_to_send = ceil(total stored bytes × read_percent / 100)
```

The response begins at byte zero. It is not based on words, lines, chapters, pages, or rendered layout. A partial text, Markdown, or HTML response may therefore end mid-line, mid-markup, or mid-character.

## Sandboxed HTML reading

HTML Read/Preview responses use `text/html; charset=UTF-8` and restrictive response headers. The Content Security Policy applies a sandbox, blocks scripts, forms, frames, objects, connections, and base-URL changes, and does not grant `allow-scripts` or normal PSCOT-origin privileges.

## First-party analytics

PSCOT records internal aggregate activity in SQLite without third-party analytics. The Circulation Desk reports catalog totals, authors, tags, views, approximate distinct visitors, Reads, Previews, Downloads, and Amazon hits.

A random first-party visitor token is stored in an `HttpOnly`, `SameSite=Lax` cookie and marked `Secure` on HTTPS. PSCOT stores only a one-way SHA-256 hash of the token. It does not store visitor IP addresses or full user-agent strings for these analytics.

## Fresh installation

For a new site:

```bash
/usr/local/bin/php ~/sites/pscot.com/bin/install.php
/usr/local/bin/php ~/sites/pscot.com/bin/check.php
```

The installer creates the private directories and SQLite database, then seeds the initial librarian, author, tags, and prepared views.

## Backups

```bash
/usr/local/bin/php ~/sites/pscot.com/bin/backup.php
```

Backups are written under `~/data/pscot.com/backups/`. Copy backups off the hosting account for actual disaster recovery.

## Deployment checks

- Confirm the public footer links to Privacy, Terms, and License and shows `PSCOT v1.0.0`.
- Confirm `/license.php` displays the MIT License and links to `LICENSE-v1.0.0.txt`.
- Confirm the Terms page recognizes the MIT software license while reserving writing and other non-software content.
- Confirm the Desk footer shows version/copyright on the left and the public-style PSCOT image and wordmark on the right.
- Confirm `/desk/` shows the Librarian sign-in and `/admin/` redirects without a loop.
- Confirm the Desk navigation reads Circulation Desk, Catalog, Authors, Tags, Views, Settings.
- Confirm HTML Read/Preview remains sandboxed.
- Verify TXT, Markdown, and HTML permit Preview below 100 percent.
- Verify PDF, EPUB, RTF, DOC, DOCX, and ODT are forced to Read at 100 percent.
- Verify Read, Preview, Download, and Amazon actions increment their corresponding statistics.
- Confirm Privacy, Terms, and License links work at desktop and mobile widths.

## Version

Current release: v1.0.0, July 23, 2026.
