Skip to content

Make the README readable for engineers and drop MOKE and hackathon docs #36

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sc-frederick merged 1 commit into from
Nov 10, 2026
Merged

Make the README readable for engineers and drop MOKE and hackathon docs #36

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,6 @@ coverage/
.project-kit/update.json
design/reference/

# Local hackathon drawing fixtures and their archive
/Moke-Hackathon-Drawings/
/Moke-Hackathon-Drawings.zip
# Local drawing fixtures and their archive
/drawing-fixtures/
/drawing-fixtures.zip
16 changes: 4 additions & 12 deletions .project-kit/manifest.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,11 +84,10 @@
"heroCase": "docs/fixtures/hero-case.md",
"primaryDemoPlatform": "linux-x64",
"promptInstructions": {
"version": "moke-packet-review-v10",
"version": "second-set-packet-review-v11",
"source": "Author's private review-instruction repository at revision 8a0e2648738018631eaa6d24ee0b6ebaa239afb1",
"provenance": "backend/review/prompts/provenance.json",
"scope": "Whole supplied packet or selected discipline with explicit coverage, governing sources, findings and offline HTML report",
"legacyCountVersion": "moke-selected-coordination-v2",
"systemPrompt": "Pi Durable conversation agent.instructions with full master, shared method and applicable discipline files",
"findingStyle": {
"instructions": "backend/review/prompts/finding-style.md",
Expand Down Expand Up @@ -133,29 +132,22 @@
]
}
},
"hackathon": {
"sourcesCheckedOn": "2026-10-27",
"sources": [
"https://cerebralvalley.ai/e/meta-ai-developer-hackathon/details",
"https://cerebralvalley.ai/e/meta-ai-developer-hackathon/waiver"
]
},
"segmentationExperiment": {
"entrypoint": "scripts/test-sam.ts",
"cases": "experiments/sam/cases.json",
"documentation": "docs/experiments/segmentation-test.md",
"model": "sam-3.1",
"parser": "@meta-sam/parser@0.1.0",
"pdfRenderer": "Poppler pdftoppm, external test dependency",
"fixtureManifest": "Moke-Hackathon-Drawings/drawing-manifest.json",
"fixtureManifest": "drawing-fixtures/drawing-manifest.json",
"artifactDirectory": ".local/sam",
"plumbingStudy": {
"documentation": "docs/experiments/plumbing-segmentation.md",
"cropRecipe": "experiments/sam/plumbing-crops.json",
"candidateCases": "experiments/sam/plumbing-cases.json",
"refinementCases": "experiments/sam/plumbing-refinement-cases.json",
"reconciliationEntrypoint": "scripts/reconcile-fixtures.ts",
"mokeInstructions": "backend/review/prompts/assets"
"reviewInstructions": "backend/review/prompts/assets"
},
"sourcesCheckedOn": "2026-10-27",
"sources": [
Expand Down Expand Up @@ -196,7 +188,7 @@
"additionalDisciplineSets": {
"documentation": "docs/experiments/sam-expanded-sets.md",
"recipes": "experiments/sam/expanded",
"fixtureManifest": "Moke-Hackathon-Drawings/expanded/drawing-manifest.json",
"fixtureManifest": "drawing-fixtures/expanded/drawing-manifest.json",
"artifactDirectory": ".local/sam/iteration-5",
"caseCount": 42,
"cropCount": 18,
Expand Down
250 changes: 83 additions & 167 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,194 +1,110 @@
# Second Set

Second Set is a desktop workbench for reviewing engineering drawing packets, built for
the Meta AI Developer Hackathon. Import the drawings and ask for a whole-set QA
pass or a discipline review. Second Set reads source images, follows its review
instructions, records findings and coverage, and produces an offline HTML report.
Follow-up requests can deepen the review while retaining earlier issue IDs.

[Watch the narrated demo on YouTube](https://youtu.be/wl8wwq_Tlrw). Second Set was called
MOKE until November 9, 2026, so the demo and earlier records use that name.
Second Set is a desktop app that gives a drawing set a second review before
submittal. Import the PDFs and ask for a QA pass or a discipline review. Second
Set reads the sheets, lists what it finds with the evidence behind each finding,
and exports an HTML report you can share.

![Second Set's five-sheet review with 19 findings, coverage gaps, and findings navigation](docs/screenshots/workbench.png)

## The review workflow

1. **Import the packet.** Create a project and import its PDFs. Start a review
without creating a count check or manually confirming every sheet first.
2. **Ask for the review.** For example, ask "Please run a quick QA pass on this
drawing set" or "Review the electrical design and supporting calculations."
Choose a model and reviewer, or let Auto route the request. A saved note does
not start inference.
3. **Follow the inspection.** Second Set inventories the supplied sheets, opens source
images and detail crops, and records the four review passes: document
completeness, code and agency requirements, coordination, and prior comments.
A Florida code index points each check to its code section, statute or rule.
Public-source lookup with PDF text and repeatable arithmetic support the
inspection. With a Meta key, SAM 3.1 segments drawn devices and fixtures for
counts and zooms into each finding's problem area.
4. **Review the findings and gaps.** Each issue identifies its location, evidence,
correction and supporting sources or calculations. Unreviewed sheets,
inaccessible governing text and missing project inputs remain visible. Mark
a finding valid, a false alarm, not applicable or a duplicate, with a reason;
follow-up questions in the same conversation read that decision. A firm
checklist in Review settings applies the firm's own checks to new reviews.
5. **Export the report.** The self-contained HTML includes findings, embedded
evidence, coverage, citation status, calculations and prior-comment tracking.
Its Completed checkboxes track the user's corrections separately from finding
status and reviewer-verified closure. Export a complete package to preserve
the source files and execution history as well.
## What it checks

Each sheet gets four passes: document completeness, code and agency
requirements, coordination between disciplines, and follow-up on prior review
comments. Code findings cite the Florida code section, statute or rule they rely
on.

A whole-set review covers general, building design, civil, structural,
mechanical, electrical, plumbing, fire alarm, fire sprinkler, fire protection and
life safety. You can also ask for one discipline.

With a Meta key, SAM 3.1 locates drawn devices and fixtures so they can be
counted, and zooms into the area each finding is about.

## Running a review

1. **Create a project and import the PDFs.** You don't need to confirm sheets
or set up count checks first.
2. **Ask for the review.** Click **Initial Review** for a full first-submittal
review, or type a request such as "Run a quick QA pass on this drawing set" or
"Review the electrical design and supporting calculations."
3. **Work through the findings.** Each finding gives the sheet and location, the
evidence, the correction needed, and its code sources or calculations. Open a
finding to see the source drawing beside it. Mark it valid, a false alarm,
not applicable or a duplicate, and give a reason. Follow-up questions and
reviews in the same conversation take that decision into account.
4. **Export the report.** The report is a single HTML file with the findings,
evidence images, coverage, code citations, calculations and prior-comment
tracking. Use its Completed checkboxes to track corrections.

![A saved false-alarm decision beside the source drawing and SAM highlight](docs/screenshots/correction.png)

Revision reviews carry earlier findings into the revised sheets. The demo also
shows [a finding that remained open](https://youtu.be/wl8wwq_Tlrw?t=122) on a
13-sheet set reviewed on October 31.
When revised sheets arrive, import them and ask for a recheck. Earlier findings
keep their issue IDs, and a finding closes only after the review inspects the
revised sheet.

To apply your firm's own checklist to new reviews, add it in Review settings.

## Limits

- Findings are model review results. They are not professional approval, and a
finished review does not replace your own check.
- The report lists any sheets that were not reviewed. Code text that could not be
opened, unknown code editions and missing project information show as
**Needs input**.
- A citation marked **Indexed** has a known section and link. Open the link to
confirm the wording.
- SAM highlights show where a symbol appears on the sheet. They do not measure
dimensions.

## Where your drawings go

Drawn-to-schedule count comparisons remain available as specialized checks.
Reviewers accept their count inputs and coverage before deterministic comparison;
corrections and revision rechecks retain their history. The
[two-sheet count demonstration](docs/fixtures/hero-case.md) exercises a supported
issue, corrected false alarm, unchanged control and revision recheck.
Projects are stored on your computer. A review sends drawing images to the model
provider you choose: Meta, Baseten, OpenCode Go, or a custom endpoint you add.

A review report states what was actually inspected. Model findings are review
results, and a finished execution does not provide professional approval.
Regulatory findings need applicable governing sources; unavailable sources and
unknown editions remain Needs input. SAM geometry does not establish physical
dimensions.
The model offered through OpenCode Go, Muse Spark 1.3 Contributor, trains Meta's
models on your drawings. Don't connect OpenCode Go for drawings that can't be
shared.

**Push to cloud** uploads your whole Second Set workspace, including every
project and its original PDFs, to a cloud sandbox. The review runs there, and the
results come back to your computer. It needs a one-time setup; see
[cloud reviews](docs/cloud-reviews.md).

## Install

Download the installer for Windows, macOS (Apple silicon) or Linux from
[GitHub Releases](https://github.com/Surfside-Software/second-set/releases/latest).
The installers are unsigned. macOS can block the first launch; allow it under
System Settings › Privacy & Security › Open Anyway. On Linux, make the AppImage
executable or install the `.deb`. Model reviews need a provider key; see
[inference setup](docs/inference.md).

### Upgrading from MOKE 0.2.2

- Second Set installs as a new app beside MOKE and opens MOKE's projects from the same
data folder. Don't run both at once; uninstall MOKE when you're done with it.
- On macOS and Linux, keys saved in MOKE may not unlock. Enter them again in Review
settings or import them from the File menu; the keys that still unlock keep working.
- A review paused in MOKE can't resume. Start a new review; finished reviews and their
reports are unchanged.
- `MOKE_*` environment variables are now `SECOND_SET_*`, for example
`SECOND_SET_MODAL_CONFIG` and `SECOND_SET_SESSION_CREDENTIAL_FILE`. A saved Modal
configuration needs `appName` `second-set-reviews` and `imageName`
`second-set-review-engine:latest`, and each provider Secret needs the key
`SECOND_SET_API_KEY`; see [cloud reviews](docs/cloud-reviews.md).

## How it works

| Process | Owns |
| ------------------ | ---------------------------------------------------------------------------------------------- |
| SvelteKit renderer | Projects, conversations, findings, and source inspection |
| Electron | Windows, menus, file dialogs, protected credentials, and the trusted renderer bridge |
| Bun backend | Effect application services, SQLite, PDF workers, evidence, calculations, and review execution |

Effect Schema contracts validate process messages. The renderer uses Effect RPC
over authorized Electron MessagePorts; Electron forwards application requests to
Bun over authenticated loopback HTTP. Database access and provider credentials
stay outside the renderer.

Pi Durable journals the review and runs the full vendored review instructions. A
separate ledger records model and SAM intent before dispatch, preserving unknown
outcomes without automatic resends. Reviews have pause and cancel controls and an
optional call budget. The default packet review has no application call ceiling;
long conversations use Pi compaction. Complete packages export and restore the
database, original PDFs, rendered evidence and execution journals together.

Projects run locally, but inference uses hosted Meta, Baseten or OpenCode Go APIs,
or a custom endpoint you add, and sends selected drawing evidence to that provider. **Push to cloud** transfers the complete
workspace for a new bounded review, streams progress, and automatically syncs results with local
ownership checks. See [cloud setup and limits](docs/cloud-reviews.md),
[the runtime decision](docs/review-runtime.md), and
[data and recovery](docs/data.md).

## Development

Install the Bun version pinned in [.bun-version](.bun-version), then run:
The installers are unsigned. If macOS blocks the first launch, open System
Settings › Privacy & Security and click Open Anyway. On Linux, make the AppImage
executable or install the `.deb`.

```sh
bun install --frozen-lockfile
bun run dev
```
Reviews need a key from a model provider; [inference setup](docs/inference.md)
explains how to add one. Without a key you can still import drawings and run
manual count checks.

You can import drawings and use manual count checks without provider keys.
For model review, copy [.env.example](.env.example) to `.env` and set
`OPENCODE_API_KEY`, `MODEL_API_KEY` or `BASETEN_API_KEY`. With a Go key, reviews run
on Muse Spark 1.3 Contributor through OpenCode Go, and Meta's API is used only for
SAM and count checks. Contributor trains on your drawings, and Go refuses it until
a workspace owner allows that. Otherwise choose
Muse Spark, Muse Wonder or Baseten Muse Spark Open in the app.
Restart after changing credentials. See [inference setup](docs/inference.md) for
packaged-app credentials, model capabilities and optional review budgets.
If you used version 0.2.2, read the [upgrade notes](docs/upgrading.md) first.

Bun runs tools and the application backend. The packaged app includes the Bun
executable, PDF renderer, and native assets; users do not install Bun or Node.
Build installers with `bun run package:desktop`. See [desktop builds and releases](docs/deployment.md).
## For developers

## Verification
Install the Bun version pinned in [.bun-version](.bun-version), then run:

```sh
bun run verify # checks, smoke tests, builds, and Electron end-to-end tests
bun run test:packaged # after packaging, repeat the desktop flow against the packaged executable
bun run test:screenshots # offline fixture captures in test-results/
```

Tests use real local databases, RPC, PDF workers, and Electron. Hosted-provider
boundaries use local transports; normal verification requires no keys and makes
no paid requests. Headless Linux needs an X display, for example
`xvfb-run -a bun run verify`. Install Poppler for the optional experiment smoke
tests; they skip explicitly when `pdftoppm` is unavailable.

The README screenshots are frames from the narrated demo, showing actual review
results and saved decisions. The [screenshot source notes](docs/screenshots/README.md)
record the video and frame timestamps. [Development and testing](docs/development.md)
explains the suite layout, offline fixture captures, and toolchain.

## Repository layout

```text
src/ SvelteKit workbench and shared Effect Schema/RPC contracts
desktop/ Electron shell, preload, and backend connection
backend/ Application services, PDF workers, inference, and review storage
migrations/ Immutable SQLite migrations
tests/ Smoke tests, Electron end-to-end flows, and synthetic fixtures
scripts/ Development, build, packaged checks, and opt-in model experiments
docs/ Setup, architecture, screenshots, and validation evidence
experiments/ SAM recipes, captured proposals, and research evidence
bun install --frozen-lockfile
bun run dev # run the app from source
bun run verify # checks, tests, builds, and Electron end-to-end tests
```

The [documentation index](docs/README.md) separates setup and architecture from
validation records and drawing experiments. The [workbench design notes](docs/design.md)
record the Forge design system, its adaptations, and third-party asset attribution.

## Hackathon provenance

This entry addresses **Build for Your World**. The application work in this
repository began on October 27, 2026. The [rules and evidence review](docs/validation/hackathon-readiness.md)
maps the public repository, Meta model integration, demo, and source attribution
to the participant guide checked on November 4.

The review prompts and the owner's 2023 Florida Building Code plan-review
reference predate this entry. The code index tooling and
`florida-code-additions.md` were added during the hackathon; see the
[code index provenance](backend/review/code-index/README.md).
This repository implements a fresh application from the project-kit desktop starter, with drawing evidence,
corrections, and revision tracking built for the hackathon. It does not reuse the
earlier MOKE application. The project was renamed from MOKE to Second Set on
November 9, 2026, and no longer uses the MOKE name. Pi Durable provides agent execution as an MIT-licensed
dependency; the new work is the drawing-review application, evidence handling,
corrections, revision behavior and portable review execution. Prompt and
dependency provenance live in
[the project manifest](.project-kit/manifest.json) and
[the review prompt sources](backend/review/prompts/README.md).
For model reviews from source, copy [.env.example](.env.example) to `.env` and
add a provider key. The app is an Electron shell around a SvelteKit interface and
a bundled Bun backend, which owns the SQLite database, PDF processing and review
execution. [Development and testing](docs/development.md) covers the commands and
test suites, and the [documentation index](docs/README.md) lists the
architecture, release and validation records.

## License

Second Set is released under the [MIT License](LICENSE). Vendored code and third-party
assets keep their own licenses. The styles in `src/lib/forge.css` are adapted from
Uiverse Design's Forge and remain under its license; see
Second Set is released under the [MIT License](LICENSE). Vendored code and
third-party assets keep their own licenses. The styles in `src/lib/forge.css` are
adapted from Uiverse Design's Forge and remain under its license; see
[the design notes](docs/design.md).
4 changes: 2 additions & 2 deletions backend/review/code-index/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ one-line plan review note and a link. The index contains no copied code text.

`assets/FBC_2023_plan_review_reference.md` is the owner's plan review reference
for the 2023 Florida Building Code, 8th Edition, last modified 2026-07-09. It
predates the hackathon and is vendored unmodified; the formatter ignores it.
`assets/florida-code-additions.md` was written for this entry on 2026-10-30. It
predates this application and is vendored unmodified; the formatter ignores it.
`assets/florida-code-additions.md` was written for this application on 2026-10-30. It
adds Florida Statutes, Florida Administrative Code rules, the Florida Fire
Prevention Code adoption, the 9th Edition (2026) volumes and the 8th Edition
supplements. `provenance.json` records both files' origin and SHA-256.
Expand Down
Loading
Loading