Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 2 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,5 @@ Who needs this change, what failed before, and what can they do afterward?
- [ ] No credentials, personal applications, or private research are included.
- [ ] Agent findings are fixed or answered with evidence.
- [ ] A maintainer other than the author will approve.

- [ ] Public capabilities, integration limits and lead-engineer credit match `docs/public-copy.json`; run `pnpm public-copy:check` and follow `docs/PUBLIC-COPY.md` when these change.
1 change: 1 addition & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ jobs:
- run: pnpm lint
- run: pnpm typecheck
- run: pnpm test
- run: pnpm public-copy:check
- run: pnpm build
- name: Bundle the production gateway with the built application
run: node scripts/release/prepare.mjs
Expand Down
43 changes: 32 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,34 @@
# Relay by SyberLabs

<!-- relay:public:start -->
**Your job search should remember what you've done.**

Relay is a job-search review workspace for people working with AI assistants. Bring research from multiple sources into one job history, prepare exact drafts, and keep interview follow-ups alongside the application.
A job-search review workspace that keeps research, application history, and exact accepted drafts together across your tools.

**Lead engineer: [Seth Carlson](https://github.com/sdcarlson).**

## Available in this early release

- Consolidate repeated posting URLs and preserve research history.
- Edit notes and follow-up drafts on submitted jobs and active interviews without resetting their status.
- Accept an exact draft; changing it returns it to review.
- Import Notion research through a read-only command connector.
- Use Obsidian for role research, interview notes and follow-up planning; preview selected notes together, return drafts to their original job version, and export job context with source history.
- Prepare drafts through the Claude API using your verified facts and your own credentials.
- Exchange validated research and draft files with Grok Bot in its VM.
- Explore fictional example records. No real applicant data is included.
- Consolidate repeated posting URLs while preserving source history.
- Keep interview notes and follow-ups without resetting application status.
- Accept an exact draft; changing the wording requires review again.
- Explore fictional example records; no real applicant data is included.

## Integrations

- **[ChatGPT](integrations/OPENAI.md)**: Prepared prompts and JSON file handoffs for draft review.
- **[Codex](integrations/OPENAI.md)**: Prepared prompts, validated draft files, or local drafting through the signed-in Codex CLI.
- **[Obsidian](integrations/OBSIDIAN.md)**: Selected research notes, version-bound draft notes, and job context exports.
- **[Notion](integrations/README.md)**: Read-only research import through the local command connector.
- **[Claude](integrations/README.md)**: Draft preparation through the Claude API with your own credentials.
- **[Grok Bot](integrations/GROK_BOT.md)**: Validated research and draft file exchange in the Bot's VM.

Integrations require explicit setup or file handoffs. Returned drafts require human review. No automatic application sending or background account sync is included.

ChatGPT uses a prompt/file handoff; Codex also supports a local CLI adapter. This release does not include a hosted ChatGPT app or MCP connection.

[Integration setup](integrations/README.md) | [Grok Bot instructions](integrations/GROK_BOT.md) | [Launch copy](LAUNCH.md)
[Integration setup](integrations/README.md) | [ChatGPT and Codex guide](integrations/OPENAI.md) | [Launch copy](LAUNCH.md)
<!-- relay:public:end -->

[Development workflow](CONTRIBUTING.md) | [Delivery and review](docs/delivery.md) | [Team board](https://github.com/orgs/SyberLabs/projects/1)

Expand All @@ -29,12 +42,20 @@ This is a pinned copy of the separately maintained, MIT-licensed [GrokCell proje

## Obsidian workflow

Select a job, open **Connect Obsidian, Grok Bot, Notion & Claude**, choose the note purpose and **Create note for selected job**. Edit the downloaded note in your vault, then load it in Relay, review its contents and preview matches before importing. New jobs can start from the downloadable example. Several research notes can be imported together.
Select a job, open **Connect your tools**, choose the note purpose and **Create note for selected job**. Edit the downloaded note in your vault, then load it in Relay, review its contents and preview matches before importing. New jobs can start from the downloadable example. Several research notes can be imported together.

Use **Edit draft in Obsidian** for an application or follow-up draft that returns to the same job version for review. **Download job context** includes source history as a reference snapshot. Research preserves existing status and approval; loading a draft never accepts or sends it. This is an explicit file handoff, with no plugin, vault scanning or background synchronization.

[Complete Obsidian guide](integrations/OBSIDIAN.md) | [Architecture and data ownership](ARCHITECTURE.md)

## ChatGPT and Codex

Choose **Prepare for ChatGPT** or **Prepare for Codex** in **Connect your tools**, share the selected prompt, and return the JSON result for review. Codex can also prepare drafts through its signed-in CLI. [Complete setup and boundaries](integrations/OPENAI.md).

## Keeping public pages current

The project, organization, personal profile and website share one [maintained product description](docs/public-copy.json). [Public-copy process](docs/PUBLIC-COPY.md) explains generation, checks and automatic refreshes.

## Run locally

Node 24 and pnpm are required. From the repository root:
Expand Down
6 changes: 4 additions & 2 deletions app/about/page.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ export default function About() {
<b>Bring your assistant</b>
<p>
Import Obsidian or Notion research and exchange draft packets with
Grok Bot or Claude.
ChatGPT, Codex, Grok Bot or Claude.
</p>
</div>
</section>
Expand All @@ -57,7 +57,9 @@ export default function About() {
local command integrations. Obsidian notes can be selected for import,
and job snapshots downloaded into your vault. Notion imports are
read-only. Claude uses your API credentials. Grok Bot uses a documented
file handoff in its VM.
file handoff in its VM. ChatGPT uses a prepared prompt and JSON file
handoff. Codex supports the same handoff or a local command using your
signed-in Codex CLI. Every returned draft requires review.
</p>
<p>
Relay does not yet run an autonomous job hunt or send applications. Live
Expand Down
55 changes: 49 additions & 6 deletions app/connections.tsx
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
'use client';
import { useState } from 'react';
import Link from 'next/link';
import { assistantPrompt, type Assistant } from '../lib/assistant-handoff';
import { type EditorTarget } from '../lib/editor';
import {
obsidianNote,
Expand Down Expand Up @@ -58,7 +59,7 @@ export function Connections({
const [workflow, setWorkflow] =
useState<keyof typeof obsidianWorkflows>('research');
const [loading, setLoading] = useState(false);
function download() {
function download(assistant?: Assistant) {
if (!current) return;
const packet = {
schema: 'relay.packet.v1',
Expand All @@ -73,6 +74,23 @@ export function Connections({
facts,
draft,
};
if (assistant) {
try {
downloadFile(
assistantPrompt(packet, assistant),
`relay-${assistant}-prompt.md`,
'text/markdown',
);
setNote(
'Prompt downloaded. Share it with your chosen assistant, save its JSON response, then load that file here for review. Only this job, the visible draft and supplied facts are included.',
);
} catch (error) {
setNote(
error instanceof Error ? error.message : 'Unable to prepare handoff.',
);
}
return;
}
downloadFile(
JSON.stringify(packet, null, 2),
'relay-packet.json',
Expand All @@ -85,12 +103,12 @@ export function Connections({
return (
<details className="import">
<summary>
<b>Connect Obsidian, Grok Bot, Notion & Claude</b>
<b>Connect your tools</b>
</summary>
<p>
Bring research from Obsidian, Notion or Grok Bot, and review a draft
prepared by Claude. Load Obsidian notes directly; other integrations use
the Relay command tool. Accounts are not connected automatically.
Bring research from Obsidian, Notion or Grok Bot, and review drafts
prepared with ChatGPT, Codex or Claude. Choose which files to share.
Accounts are not connected automatically.
</p>
<p>
<Link href="/about">About Relay and integration setup ↗</Link>
Expand Down Expand Up @@ -203,9 +221,27 @@ export function Connections({
/>
</label>
<div className="actions">
<button className="secondary" disabled={!current} onClick={download}>
<button
className="secondary"
disabled={!current}
onClick={() => download()}
>
Download selected job packet
</button>
<button
className="secondary"
disabled={!current}
onClick={() => download('chatgpt')}
>
Prepare for ChatGPT
</button>
<button
className="secondary"
disabled={!current}
onClick={() => download('codex')}
>
Prepare for Codex
</button>
<label className="secondary">
Load research or draft
<input
Expand Down Expand Up @@ -255,6 +291,13 @@ export function Connections({
/>
</label>
</div>
<p>
For ChatGPT or Codex, enter verified facts, download the prepared
prompt, and share it with that assistant. Save its JSON response as a
.json file and load it here. Codex can also prepare a draft through the
local command tool. Returned wording needs review; loading never accepts
or sends it.
</p>
{loading && <output>Reading selected files…</output>}
{note && <output>{note}</output>}
</details>
Expand Down
11 changes: 11 additions & 0 deletions docs/OPENAI-RELEASE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# ChatGPT and Codex integration verification - September 5, 2026

Lead engineer: Seth Carlson.

- Added browser prompt exports for ChatGPT and Codex, local prompt/draft packaging commands, and `codex-run` using the signed-in Codex CLI.
- A real local `codex-run` invocation completed with fictional job facts. The returned `relay.draft.v1` result passed Relay's file validation, preserved job identity and version, and retained `reviewRequired: true`. No application was sent. The private smoke-test packet/result are ignored and are not part of this release.
- After integrating the protected delivery foundation (#14), all 66 unit tests passed, including five assistant tests and five public-copy tests. Type checking, lint, public-copy validation, the production build, API contracts and compiled production gateway checks passed. All three Chromium journeys passed, including prompt downloads for both assistants, returned-file loading without acceptance, explicit save/reload and stale-result rejection. The browser response file was a fictional fixture; it was not an actual ChatGPT response.
- ChatGPT's manual conversation/file-upload path was not exercised in a signed-in ChatGPT browser. Its generated prompt, JSON response contract and Relay import validation were checked locally.
- This release does not add an authenticated hosted ChatGPT app, remote MCP server or automatic acceptance. Relay application deployment is separate from publishing its source and public descriptions.

See [setup](../integrations/OPENAI.md) and [public-copy maintenance](PUBLIC-COPY.md).
36 changes: 36 additions & 0 deletions docs/PUBLIC-COPY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Keeping Relay's public pages current

**Owner: Seth Carlson, lead engineer.** Update [`public-copy.json`](public-copy.json) when shipped behavior, integration setup, ownership or release status changes. It is the single source for the managed RELAY sections in:

- `SyberLabs/relay` - project `README.md`
- `SyberLabs/.github` - organization `profile/README.md`
- `sdcarlson/sdcarlson` - personal `README.md`
- `SyberLabs/SyberLabs.github.io` - the RELAY integration paragraph on `syberlabs.space`

Other projects, biography text and website design remain independently maintained. The generator changes only text between `relay:public:start` and `relay:public:end`. Missing or duplicate markers stop the update.

## At every product change

1. Implement and test the behavior. Update its detailed integration guide, including verification limits.
2. Review `docs/public-copy.json`. Describe implemented behavior only; keep proposed integrations and unverified account access labeled. If no public facts changed, no metadata edit is needed.
3. Run `pnpm public-copy:sync`, then `pnpm public-copy:check` and `pnpm test`. Commit generated project copy with the implementation. The canonical **CI** workflow checks for stale project copy as part of its required quality job on pushes and pull requests.
4. After the change reaches `main`, the target repositories pull the canonical description on their next scheduled run. Each has a **Sync Relay public copy** workflow with a **Run workflow** button for an immediate refresh. No shared cross-repository personal token is needed; each workflow can write only its own repository.
5. Check the workflow results and, for the website, the published page. Missing permissions, removed markers or a concurrent push fail visibly rather than overwriting unrelated work or force-pushing.

## Refresh cadence and limits

The three downstream workflows check every 15 minutes and on edits to their managed page or workflow. They commit only when the generated text changes. The website explicitly requests a Pages build after a bot commit because bot pushes do not themselves guarantee a Pages deployment.

This is eventual synchronization, not an instantaneous guarantee. GitHub schedules can be delayed, and scheduled workflows in public repositories can be disabled after prolonged inactivity. Follow GitHub's workflow failure notifications and check the Actions page if copy does not refresh. The manual workflow button is the recovery path. Organization policy or branch protection may require adapting the write step to your review process.

Automation distributes reviewed facts; it cannot prove that prose still matches new product behavior. The product-change checklist remains the owner's responsibility. Do not edit a generated section by hand; the next refresh will restore it from the canonical source.

For a local preview of another target:

```sh
node scripts/sync-public-copy.mjs --target organization --root /path/to/org-checkout --check
node scripts/sync-public-copy.mjs --target profile --root /path/to/profile-checkout --check
node scripts/sync-public-copy.mjs --target website --root /path/to/website-checkout --check
```

Omit `--check` to update only the managed section. Sources: [GitHub schedule behavior](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule), [request a Pages build](https://docs.github.com/en/rest/pages/pages#request-a-github-pages-build).
24 changes: 24 additions & 0 deletions docs/public-copy.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
{
"name": "RELAY",
"tagline": "Your job search should remember what you've done.",
"summary": "A job-search review workspace that keeps research, application history, and exact accepted drafts together across your tools.",
"repository": "https://github.com/SyberLabs/relay",
"leadEngineer": "Seth Carlson",
"leadProfile": "https://github.com/sdcarlson",
"stage": "Early release",
"capabilities": [
"Consolidate repeated posting URLs while preserving source history.",
"Keep interview notes and follow-ups without resetting application status.",
"Accept an exact draft; changing the wording requires review again."
],
"integrations": [
{ "name": "ChatGPT", "description": "Prepared prompts and JSON file handoffs for draft review.", "guide": "integrations/OPENAI.md" },
{ "name": "Codex", "description": "Prepared prompts, validated draft files, or local drafting through the signed-in Codex CLI.", "guide": "integrations/OPENAI.md" },
{ "name": "Obsidian", "description": "Selected research notes, version-bound draft notes, and job context exports.", "guide": "integrations/OBSIDIAN.md" },
{ "name": "Notion", "description": "Read-only research import through the local command connector.", "guide": "integrations/README.md" },
{ "name": "Claude", "description": "Draft preparation through the Claude API with your own credentials.", "guide": "integrations/README.md" },
{ "name": "Grok Bot", "description": "Validated research and draft file exchange in the Bot's VM.", "guide": "integrations/GROK_BOT.md" }
],
"boundary": "Integrations require explicit setup or file handoffs. Returned drafts require human review. No automatic application sending or background account sync is included.",
"openaiBoundary": "ChatGPT uses a prompt/file handoff; Codex also supports a local CLI adapter. This release does not include a hosted ChatGPT app or MCP connection."
}
2 changes: 1 addition & 1 deletion integrations/OBSIDIAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Obsidian holds editable research and interview notes. Relay holds the opportunit

## Start with one opportunity

Open Relay's **Connect Obsidian, Grok Bot, Notion & Claude** panel. If the opportunity is already in Relay, select it, choose the note purpose, then **Create note for selected job**. This fills in the job name, posting URL and a unique note ID. Move the downloaded file into your vault and edit it there.
Open Relay's **Connect your tools** panel. If the opportunity is already in Relay, select it, choose the note purpose, then **Create note for selected job**. This fills in the job name, posting URL and a unique note ID. Move the downloaded file into your vault and edit it there.

For an opportunity that is not yet in Relay, use **Download example note** and replace its example job details. The note must begin with properties like these:

Expand Down
Loading
Loading