# LoreLoom Private Alpha Testing Guide

## What LoreLoom Is

LoreLoom is a lightweight writing and worldbuilding app for long-form fiction work.

Right now it is designed around a few practical ideas:

- your writing should remain usable without AI
- your work should stay exportable and understandable
- the app should be able to run on modest self-hosted hardware later
- the writing flow should stay calm, local-first, and low-friction

## Current Alpha Status

LoreLoom is in private alpha and active development.

This build is for early hands-on testing, not production use. It is useful for exploring the writing flow, structure tree, codex workflow, and persistence behavior, but rough edges are expected.

Please treat it as early testing software:

- keep your own backups
- avoid putting anything irreplaceable into it yet
- expect bugs, unfinished areas, and behavior that may change

## How Testers Should Access It

Your tester host should tell you which setup to use.

Common options:

- local development build
- home-LAN Docker deployment
- a private LAN or reverse-proxied test instance

If you are using the current Docker Compose setup, the app is typically available at:

- [http://localhost:8088](http://localhost:8088)

If you are testing on another machine in the same network, use the host machine's LAN address and port instead, for example:

- `http://192.168.x.x:8088`

## Features To Try

Please spend time using the normal writing flow, not only clicking around menus.

Good areas to test:

- creating projects
- building a structure tree
- creating child structure nodes
- creating text blocks inside structure nodes
- renaming, moving, and deleting text blocks
- editing text block titles and body content
- Focus Mode
- Continue in New Text Block
- Codex entry creation, editing, and deletion
- Codex Lookup inside Focus Mode
- live writing stats
- command palette navigation
- project backup export and import
- Story TXT export
- Book Preview
- revision snapshots and snapshot restore
- diagnostics page and diagnostic bundle export
- persistence after refresh, browser restart, and app restart

## What Kinds Of Bugs To Report

The most helpful bug reports are concrete and reproducible.

Please report things like:

- writing not saving correctly
- content appearing under the wrong structure node
- text blocks or codex entries disappearing unexpectedly
- refresh or restart causing missing work
- sync states getting stuck on syncing, offline, or conflict
- imports or exports failing
- Book Preview not matching the project structure
- Focus Mode not returning safely
- command palette navigation taking you to the wrong item
- revision snapshots not being created or restored correctly
- diagnostic export failing
- layout or usability problems on smaller screens
- keyboard shortcuts not working or conflicting

When possible, include:

- what you were trying to do
- the exact steps you took
- what you expected
- what actually happened
- whether the backend was running
- whether you were testing on localhost, LAN HTTP, or Docker

## What Not To Put Into LoreLoom Yet

Please do not use private alpha builds for anything you cannot afford to lose or expose accidentally.

For now, avoid putting in:

- final manuscript drafts with no outside backup
- sensitive personal information
- private client work
- confidential research notes
- passwords, API keys, or secrets
- anything you would be uncomfortable sharing in a manual diagnostic review

The diagnostic bundle deliberately excludes writing content, but this is still early software and caution is appropriate.

## How Autosave And Backend Sync Work

LoreLoom currently uses a local-first model.

### Autosave

Autosave saves your current work in the browser immediately while you write.

That means:

- the editor should keep saving locally even if the backend is unavailable
- refreshing the browser should usually bring your recent local work back
- browser-local persistence is still the primary editing state

### Backend Sync

Backend sync is a second layer of durability.

It does not replace local editing. Instead, it tries to mirror your project data to the backend after safe points such as:

- after edits settle
- when leaving a text block
- when leaving a project
- after Continue in New Text Block
- after imports or restore actions
- on page hide when possible

If the backend is unavailable:

- the app should still open
- writing should still work
- local autosave should still work
- sync should retry later when possible

If a sync conflict happens, LoreLoom should preserve local work and show a conflict state instead of silently overwriting data.

## How Project Backup Export Works

Project backup export is a manual safety tool.

Use it when you want a portable backup of a project that you can inspect, archive, or re-import later.

Current backup behavior:

- export is a human-readable JSON file
- it includes project structure and technical project data
- it includes codex entries
- it includes revision snapshots
- it does not depend on the backend being available

Project backup import is also manual. It should create or merge imported project data without replacing unrelated local projects.

## How Diagnostic Bundle Export Works

LoreLoom has a diagnostics page with a manual export action:

- `Export Diagnostic Bundle`

This creates a diagnostic `.json` file that you can inspect yourself before sharing it.

Nothing is uploaded automatically. Nothing is emailed automatically. Sharing is always manual.

## What Diagnostic Bundles Include

The diagnostic bundle is meant for debugging and support, not content collection.

It may include:

- app version and build timestamp when available
- frontend environment information
- backend health information when reachable
- diagnostics summary information
- recent diagnostics events
- sync status information
- sync errors or conflict states
- project counts
- text block counts
- codex entry counts
- revision snapshot counts
- storage availability information
- approximate local storage usage when available

## What Diagnostic Bundles Exclude

The diagnostic bundle is designed to exclude writing content and titles.

It should not include:

- manuscript text
- text block content
- codex content
- revision snapshot content
- project titles
- text block titles
- codex titles
- search queries

Allowed technical details may still include things like:

- IDs
- timestamps
- event types
- sync states
- generic error messages

## Known Limitations

Current limitations to keep in mind:

- this is still early alpha software
- browser-local persistence is still important to the writing flow
- backend sync is still early and testing-oriented
- there is no multi-user collaboration
- there is no auth system yet
- there is no polished cloud sync yet
- there is no final wiki or PDF export yet
- conflict handling is intentionally conservative and does not auto-merge

## How To Safely Test Persistence

If you want to test whether persistence is working, use a cautious loop:

1. create or edit a small project
2. wait a moment after typing so autosave and sync have time to settle
3. refresh the browser
4. confirm the latest local changes are still visible
5. if the backend is running, close and reopen the app again
6. if you are testing Docker or a hosted LAN instance, restart the stack and re-open the project

Useful persistence checks:

- create a project, refresh, and confirm it still exists
- create a structure node and a text block, refresh, and confirm placement is unchanged
- edit text, refresh, and confirm the text is still present
- create a revision snapshot trigger by leaving the editor, then reopen and confirm snapshots exist
- export a project backup before more destructive tests

For riskier persistence testing:

- export a project backup first
- avoid using only one copy of important work
- if you are testing Docker persistence, confirm the SQLite data directory is mounted and retained across restarts

## Final Reminder

LoreLoom is promising as a writing prototype, but it is still early testing software.

Please use it to help us learn:

### Support And Feedback

If you need help, want to report a bug, or have suggestions, please use the LoreLoom Discord:

- [Join the LoreLoom Discord](https://discord.gg/ktUw2gsyAW)

It is the easiest place for:

- help
- bug reports
- suggestions
- tester feedback

- where the writing flow feels strong
- where persistence feels fragile
- where sync or recovery feels unclear
- where the UI gets in the way

Practical, specific tester feedback is the most useful thing at this stage.
