SAGARELIC / FIELD GUIDE / VERSION 1.0.0

Pass on the collection.
Keep the context.

A practical guide to preparing a reviewed, local photo catalogue from your own tables and images.

Tested with Google Chrome 152.0.7977.82 on Ubuntu 22.04.5 LTS. The app and exported catalogue work from local files without a server or network. Other browsers, operating systems, mobile devices, spreadsheet applications and collection systems have not been verified.

01 / Your first result

Extract the entire buyer ZIP into a normal folder. Open app/index.html in desktop Chrome. Keep the app files together. You do not need an account, installation, command line or internet connection. Python is optional for the integrity checker only.

1. Select Explore Lantern Quay. This loads four fictional objects and six original illustrations. Nothing is uploaded.
2. Inspect the suggested mapping: objects use id and title; relationships use object_id, path, order and caption. Select Apply mapping & review.
3. The example starts with 0001, 0002 and 0003 selected; 0004 is excluded. Public fields are id, title and date. Keep donor_note unchecked. Use Inspect record to see which values stay private.
4. Review all seven relationship rows. In row 6, for 0003 / missing.jpg, choose Keep missing label. The other six rows have matching images. Row 7 belongs to the excluded badge and will not be shared.
5. Read the omissions summary. Complete all three review acknowledgments. Select Generate reviewed preview, then Open recipient preview.
6. Check the preview, return to the app and select Download recipient ZIP. Unzip it to a different folder and open its index.html.

The expected handoff

3 objects · 6 relationships · 4 unique originals · 1 missing marker. shared.jpg appears for two objects but its original bytes are copied once. The badge, orphan image, donor_note column and PRIVATE-LANTERN-47831 canary must be absent from the recipient files. The sample's malicious-looking caption is displayed as literal text.

02 / Bring your own files

Work from copies of your source exports. SagaRelic reads your files; it never writes back to them. Prepare two UTF-8 tables, both comma-delimited CSV or both tab-delimited TSV. Choose the delimiter visibly under Use your own collection. The extension does not select it automatically.

Objects table

id,title,date,private_note
0001,Example object,1924,Do not share this column

Map one column to object ID and a different column to title. Both must be nonempty; IDs must be unique. Values are exact text: 0001, 1 and 1 are different. SagaRelic does not trim or case-fold IDs. Other columns are optional, and you decide which ones to share.

Photo relationships table

object_id,path,order,caption
0001,box-1/front.jpg,0,Front view
0001,box-1/back.jpg,1,Rear maker plate

Each row links one exact object ID to one exact relative image path. Order is a nonnegative safe integer; lower values display first. Equal values retain source row order. Caption is optional; select “(none)” when there is no caption column. One image may belong to multiple objects through separate rows. A repeated object/path pair must be corrected or omitted.

For a flat image collection, choose files under Photos (flat filenames). For subfolders, choose the top photos folder; only that selected root is stripped. For example, selecting photos containing photos/box-1/front.jpg matches box-1/front.jpg. Do not put the selected folder name into your relationship path. Picking a folder replaces a prior flat selection and vice versa. The folder should contain only supported images.

Select Read selected files, review the mappings, and apply them. For your own imports, all objects initially start selected. An invalid table or image import leaves the current collection intact. Applying mappings resets row edits and sharing decisions. Object ID/title errors must be fixed in a copy of the source table and re-imported; relationship rows can be corrected in the app.

Quoted fields may contain commas, line breaks and doubled quotation marks. Duplicate or empty headers, inconsistent row widths, malformed quoting, invalid UTF-8 and NUL characters are refused. Empty data tables can load, but a handoff requires at least one selected object.

03 / Make every sharing choice explicit

1. Objects: include only the records you intend to send. Inspect their fields and linked images. Objects with no photographs remain visible as no-image records.
2. Fields: ID and title are required; all other fields are your choice. The app initially includes date if present. Unchecked field names and values are excluded from every recipient data file.
3. Relationships: inspect paths, order and public captions. Change an ID, path, order or caption directly in its row. Press Tab or leave the input to apply an edit. Filter “Needs attention” to find errors, and use pagination for more than 50 rows.
4. Missing photos: choose Keep missing label to retain a visible gap, or Omit this relation. “Use linked image” only works when the exact file is loaded. Unknown object IDs, unsafe paths and duplicate links must be corrected or omitted. Even issues on unselected objects require a decision before preview.
5. Omissions: review excluded objects, explicitly omitted relationships and excluded images. Unreferenced images are counted and never copied. Unselecting an object excludes its relationships and images unless another selected object uses them.
6. Final review: acknowledge relationships/captions/omissions, public fields/object selection, and rights/filenames/image metadata. These are your decisions, not automated privacy certification.

Original images may contain EXIF, location, names, thumbnails, camera details or other private metadata. SagaRelic copies originals unchanged and retains selected source relative filenames in manifest.json. The field allowlist does not sanitize photos. Review the original files and your permission to share them separately.

Any edit to mapping, relationships, fields or object selection disables export, clears acknowledgments and closes an open preview. Regenerate and inspect a fresh preview. A preview is a snapshot, not an editable catalogue.

04 / Export, check and reopen

Download the recipient ZIP after preview. Extract the whole archive; do not open index.html inside an archive manager. Move the extracted folder anywhere and keep its contents together. It needs no access to your app, source tables or original photos folder.

CSV formula policy: SagaRelic prefixes one apostrophe to any exported cell beginning with an apostrophe, or beginning with optional whitespace/control characters followed by =, +, - or @. Remove that one added prefix to reverse the policy. Exact original field values remain in catalogue.json and the viewer. Leading-zero IDs remain exact in the catalogue; a spreadsheet may still infer numbers when opening CSV. No Excel or other spreadsheet import has been verified.

Optional Python 3.10+ check, after extraction:

python3 tools/check_catalogue.py /path/to/unzipped-catalogue

Use the checker supplied with the buyer pack. It reports missing, changed and unexpected files against the manifest, as well as count/relationship checks. It does not prove authenticity, authorship, permissions or preservation quality. Do not edit the extracted files after checking; regenerate the handoff for changes.

05 / Save your private work

Save private project / receipt downloads a separate JSON file. It records source table/media hashes, mappings, row edits, selected objects/fields, revision, counts and whether the current preview was reviewed. It does not contain image bytes or replace your source backups. It can expose excluded relationships and source filenames: never put it in the recipient ZIP.

To resume: open the app, reload the identical original tables and media, then open Restore a private project and choose the JSON. The source content hashes, paths, schema and version must match. A changed source, incompatible schema or invalid state is rejected without replacing your current work. A successful restore always requires a fresh final review and preview.

No autosave or browser database is used. Closing/reloading loses unsaved decisions. There is no import of previously exported recipient ZIPs; retain source files and the private project for future work.

06 / Supported inputs and limits

Large sets use browser memory; allow the import to finish and keep other tabs modest. The configured limits were exercised on the test host, not benchmarked across hardware. No XLSX, SVG, TIFF, HEIC, PDF, ZIP import, native museum-system integration, automatic object identification, cloud hosting or metadata stripping.

07 / Troubleshooting

08 / Privacy, removal and the free pack

The app has no analytics, accounts, remote service, CDN or automatic uploads. Work stays in browser memory until you download it. No local-storage persistence is used. Close the tabs and delete the extracted app folder to uninstall. Delete unwanted downloads, private projects and recipient copies separately. Source files are never deleted by the app.

The free pack provides this illustrated guide and the fictional examples/templates. It does not contain the paid author app. You can study the tables and drawings or use them to evaluate your own existing workflow. The buyer app creates new reviewed catalogues from your own inputs. See LICENSE.txt for permitted use and attribution.

All illustrations are first-party fictional studies. All interface screenshots were captured from the actual running product in Chrome. SagaRelic is a bounded handoff tool, not a preservation, compliance or privacy certification. Version 1.0.0 · Perunlight.