# Build a personal tool on Log

Use this guide when a person asks their own AI to build an interface for their
boating history: for example, a repeatable spreadsheet uploader, a photo review
screen, or a view of records their connection is allowed to read. Log is the
backend for the account and its saved records. A custom tool supplies the
person's preferred source mapping and interface.

If the person wants to import once, start with [Log's import page](https://log.boating.systems/import-help.html)
or the [assistant import guide](https://log.boating.systems/agent/import.md).
Building another app is useful when the source or review process repeats.

## Start with the supported contract

1. Fetch [capabilities.json](https://log.boating.systems/agent/capabilities.json).
   It names the deployed contract version and available paths. If it is
   unavailable or returns HTML, stop; do not guess endpoints.
2. Read the [API contract](https://log.boating.systems/agent/api.md),
   [written-history JSON Schema](https://log.boating.systems/agent/history-schema.json),
   and [example handoff](https://log.boating.systems/agent/history-example.json).
   Use the published [client](https://log.boating.systems/agent/client.mjs)
   where it fits. The JSON Schema describes the accepted handoff; Log's server
   also checks semantic rules and authorization.
3. Start from the [customizable uploader](https://log.boating.systems/agent/history-uploader/)
   if the task is a spreadsheet or selected-photo workflow. Its synthetic
   sample, validator, preview flow, and client are a safer starting point than
   recreating the import logic.

For a spreadsheet, keep three models separate: the original row, the tool's
review state, and the `boating-log-history` v1 record sent to Log. For example,
map a `Sail date` column to `date` and a permanent source ID to `key`; supply
`title`, `evidence`, and at least one `sources` reference. Put an uncertain
date in `uncertainties` for review. A planned calendar event is not proof of a
completed trip, and a written day does not become a measured GPS track.

Validate the proposed bundle, preview it through `importLogHistory`, let the
person select records, then commit with each record's preview token. Show the
actual save results. Keep stable source and record keys for retries; a changed
record under an old key is refused rather than silently overwritten.

## Where Schema Lattice helps

[Schema Lattice](https://schemalattice.com) is an optional design reference
for the local AI **when it creates a durable data model or an adapter between
apps**. It can help the builder discover concepts, compare meanings, and record
why the custom app adopted or changed a concept. It is not part of Log's
authentication or import protocol.

- Boating Systems publishes its own vocabulary there, generated from the
  platform schema: Log's history handoff is the concept named in
  `capabilities.json` under `history.concept` (Written Boating Day), beside
  Vessel, Trip, Vessel Relationship, maintenance and race-series concepts.
  Adopt those for data you send to the platform.
- Ask the lattice about the concepts the tool actually owns or maps. Pass
  `ephemeral: true` so the person's wording is not kept, and
  `contexts: ["vessel-ops", "voyage-log", "equipment-maintenance",
  "sailboat-racing"]` so unrelated domains stay out. Read the response's
  `verdict`, and resolve a candidate (with the same `sessionId`) before
  adopting it; a similarity score alone does not establish that its fields
  mean the same thing.
- Once you have decided, report it with one `lattice_propose` call:
  `{ sessionId, conceptUri, verdict: "right" | "wrong", reason }`. It needs no
  key, only judges results your own search returned, and never changes
  anything until independent users agree. From an `ephemeral` session it
  counts toward totals only. Keep private details out of its `note`.
- Write down the mapping from source fields to local fields to the Log handoff,
  including units, provenance, uncertainty, and omissions, as `fieldMaps` in
  the tool's own `schemalattice.json` (the lattice's annotation standard). It
  stays in the tool; it is never sent to the catalog. Log's versioned
  schema decides the payload, even when a lattice concept suggests another
  shape.
- If no useful concept appears, say so and build against Log's contract. Do
  not fork an unrelated high-scoring result or publish a new concept merely
  to finish an uploader. If a stable, reusable concept emerges after testing,
  consider publishing it as a separate task.
- Keep private log entries, credentials, and source documents out of lattice
  searches and publications. Lattice URIs start with
  `https://schemalattice.com/` and are content-addressed, so a stored
  reference never changes meaning.

The [builder brief](https://schemalattice.com/skill/builder) is the one-page
version of these rules; the [lattice workflow](https://schemalattice.com/skill)
explains discovery, adoption, and lineage in full. A builder can use it for modeling; it still needs this
Log contract to make a working client.

## Connection and scope

Use a named, expiring, revocable Log connection only when the person is ready
to connect their running tool. A pairing code belongs in that tool, never in a
builder prompt, source file, hosted template, or lattice record. The import
grant includes reading trips and geometry as well as supported imports; tell
the person that full scope. It does not authorize publishing, deleting,
reading rosters, or entering the separate safety database. Keep credentials
in memory and stop when the grant is revoked or expires.

This contract is for Log. Chart, Vessel, and other Boating Systems apps need
their own published capabilities and grants before a custom tool can claim to
read or write their data. The shared account is not a general-purpose API key.

## Brief to give a local AI builder

Copy this request into the builder with the clean starter and synthetic data:

> Build a small interface for my recurring boating-history source. First read
> Log's capabilities, API contract, JSON Schema, and example at the links in
> this guide. Start with the supplied uploader. Show how each source field
> maps to the reviewed record and Log's v1 handoff. Use Schema Lattice while
> choosing durable concepts or mapping between apps, but let Log's contract
> decide what can be saved. Use synthetic data until the interface is ready.
> Do not ask me for a pairing code or private files in this builder chat.
> Validate and preview before saving, require my selection, and show actual
> acknowledgements. Keep the public client and server authority rules intact.

The person's authorization to search their own mail, photos, calendar, or
files is a separate request. This builder brief grants no such access.