Skip to content

Commit c762e97

Browse files
gershamgersham
committed
Refresh repository documentation
1 parent 88e3aae commit c762e97

5 files changed

Lines changed: 272 additions & 125 deletions

File tree

‎AGENTS.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# ScreenRig plugin agent guide
2+
3+
This repository owns the public ScreenRig Codex/Claude marketplace, canonical
4+
skill source, plugin metadata, and generated bundle containing a pinned CLI. It
5+
does not own the CLI source, players, backend, site, or production deployment.
6+
7+
## Sources of truth
8+
9+
- `skills/screenrig/`, `build/plugin.json`, root marketplace manifests, root
10+
public files, and `components.lock.json` are canonical inputs.
11+
- `components.lock.json` pins the exact `screenrig/cli` commit, artifact
12+
filename, and SHA-256.
13+
- `scripts/build-plugin.py` defines generation of `plugins/screenrig/`.
14+
- `scripts/validate-plugin.py` and `scripts/check-public-repo.py` define the
15+
public/reproducibility boundary.
16+
- Production deployment belongs only to the backend repository's component
17+
lock; this repository publishes an artifact and never deploys ScreenRig.
18+
19+
## Edit and generation rules
20+
21+
- Never edit `plugins/screenrig/` independently. Change canonical inputs and
22+
regenerate with the exact CLI artifact selected by `components.lock.json`.
23+
- Never copy CLI source or a local mutable build into the bundle. Update the
24+
lock only when intentionally selecting a reviewed CLI CI artifact.
25+
- Keep Codex and Claude marketplace metadata, generated manifests, public
26+
README, and skill behavior aligned.
27+
- The launcher must remain package-relative, preflight Node.js 20.11+, and
28+
execute only the bundled `cli/dist/bin.js`.
29+
- Preserve unrelated work. Do not commit, push, tag, publish, deploy, or change
30+
marketplace/GitHub state unless explicitly authorized.
31+
32+
## Product and security boundaries
33+
34+
- Teach only implemented CLI commands. The current `screen pair` parser accepts
35+
the canonical undashed six characters; `browser setup` accepts the public
36+
dashed/undashed handoff form.
37+
- Preserve automatic first-use enrollment, machine-readable output, user-private
38+
configuration outside the plugin directory, and server-first
39+
`auth revoke --yes`.
40+
- Never expose account credentials, cookies, provisioning fragments, signed
41+
URLs, customer content, raw headers, or secret-bearing output.
42+
- The plugin does not implement rendering, native auth, package caching, public
43+
handoff TTLs, or deployment; describe those only from pinned/current owning
44+
sources.
45+
- Screenshotting is outside v1 and no screenshot command may be documented.
46+
47+
## Verification
48+
49+
```sh
50+
python3 scripts/check-public-repo.py
51+
plugins/screenrig/skills/screenrig/scripts/screenrig --json version
52+
```
53+
54+
Bundle validation and reproduction require the exact locked CLI artifact:
55+
56+
```sh
57+
python3 scripts/build-plugin.py --check --cli-artifact <locked-cli-artifact>
58+
python3 scripts/validate-plugin.py --cli-artifact <locked-cli-artifact>
59+
```
60+
61+
Verify the artifact SHA-256 against `components.lock.json` first. These gates
62+
do not prove marketplace installation/loading, live enrollment, pairing, public
63+
handoff, native hardware, or production deployment.
64+
65+
## Completion evidence
66+
67+
Report canonical and generated files changed, locked CLI repository/commit/hash,
68+
generation/validation results, stale-language scan, repository status, and
69+
every skipped marketplace/live/backend/native gate. Do not claim a reproducible
70+
bundle when the exact locked CLI artifact was unavailable.

‎README.md‎

Lines changed: 67 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# ScreenRig agent plugin
22

3-
ScreenRig is an agent-first digital-signage and kiosk workflow. The canonical
4-
public marketplace source is
5-
[github.com/screenrig/plugin](https://github.com/screenrig/plugin).
3+
ScreenRig is an agent-first digital-signage workflow. This public repository is
4+
the canonical marketplace source and distributes one generated plugin containing
5+
the ScreenRig skill plus a pinned CLI artifact.
66

77
## Install
88

@@ -20,64 +20,86 @@ codex plugin marketplace add https://github.com/screenrig/plugin.git --ref main
2020
codex plugin add screenrig@screenrig --json
2121
```
2222

23-
Then open the [ScreenRig Player](https://play.screenrig.ai) and ask your agent
24-
to pair the six-character code, or paste a public
25-
`https://screenrig.ai/ABC-234` setup instruction into the agent. Do not look
26-
for or install a global `screenrig` binary: the plugin's skill invokes its
27-
pinned, bundled CLI.
23+
Confirm the installed entry and read its package root:
2824

29-
This distributable contains the ScreenRig skill and its pinned, bundled CLI.
30-
The CLI requires Node.js 20.11 or newer. The wrapper resolves only the bundled
31-
CLI; it does not download or execute a mutable command at runtime. Agent
32-
workflows use machine-readable output and keep credentials in user-private
33-
application state outside the replaceable plugin directory.
25+
```sh
26+
claude plugin list --json
27+
codex plugin list --json
28+
```
3429

35-
If a newly installed plugin is not loaded into the current agent session, run
36-
`claude plugin list --json` and read the `installPath` for
37-
`screenrig@screenrig`, or run `codex plugin list --json` and read its
38-
`source.path`. Verify that exact installation before continuing:
30+
Run `node --version` first. The package-relative launcher fails closed unless
31+
Node.js 20.11 or newer is active. After installation, use the agent's plugin list
32+
JSON to read the ScreenRig `installPath` (Claude Code) or `source.path`
33+
(Codex), then verify the installed bundle:
3934

4035
```sh
4136
<plugin-root>/skills/screenrig/scripts/screenrig --json version
4237
```
4338

44-
Then use that same package-relative wrapper for ScreenRig commands. Do not add
45-
it to `PATH` or substitute another executable.
39+
Use that same launcher for every ScreenRig command. It resolves only
40+
`<plugin-root>/cli/dist/bin.js`; it does not use a global executable or fetch a
41+
mutable command at runtime.
42+
43+
## Pairing and browser setup
44+
45+
Open `https://play.screenrig.ai` and ask the agent to pair the six-character
46+
code. The browser Player displays a middle dash such as `ABC-234`; the current
47+
default pair command requires the canonical six characters:
48+
49+
```sh
50+
<plugin-root>/skills/screenrig/scripts/screenrig --json screen pair ABC234
51+
```
52+
53+
The public homepage handoff is separate first-use convenience. An unclaimed
54+
`https://screenrig.ai/ABC-234` locator lasts 30 minutes. `browser setup --code
55+
ABC-234` accepts the dashed display form (or `ABC234`), and a successful claim
56+
creates a fresh independent 10-minute protected delivery window. CLI output is
57+
limited to the normalized code, claim status, and fragment-free Player URL.
4658

47-
The first authenticated operation creates a ScreenRig account automatically,
48-
stores its permanent credential with user-only permissions, and resumes the
49-
requested operation. The default file is
59+
The first authenticated operation enrolls automatically, stores its credential
60+
with user-only permissions outside the replaceable plugin directory, verifies
61+
it, and resumes the original request. The default configuration is
5062
`$XDG_CONFIG_HOME/screenrig/config.json` when `XDG_CONFIG_HOME` is set,
5163
`%APPDATA%\screenrig\config.json` on Windows, or
52-
`~/.config/screenrig/config.json` otherwise. `SCREENRIG_CONFIG` may select a
53-
different path. Uninstalling or upgrading the plugin does not remove this user
54-
configuration.
55-
56-
The canonical customer command is `screen pair CODE [--label LABEL]`. The
57-
plugin also supports implemented application, playlist, media, screen, event,
58-
and application K/V operations documented by the bundled skill.
59-
60-
Credential removal is explicit and server-first. `screenrig auth revoke --yes`
61-
revokes exactly the stored calling credential, issues no replacement, and
62-
removes local credential, enrollment, and transient authenticated-operation
63-
state only after the server confirms an empty `204` response. Non-secret API
64-
configuration is preserved. The account, screens, and content remain, but the
65-
revoked credential cannot be recovered in the current anonymous no-email
66-
model; the next account-scoped command enrolls a separate new account. Failed
67-
or ambiguous requests retain local state, and retrying the exact revocation is
64+
`~/.config/screenrig/config.json`; `SCREENRIG_CONFIG` may override it.
65+
66+
`auth revoke --yes` revokes the calling credential on the server before local
67+
credential and retry state are removed. Success requires an empty `204`
68+
response and issues no replacement. The account, screens, and content remain;
69+
the next account-scoped command enrolls a separate new account. Failed or
70+
ambiguous results preserve local state, and retrying the exact revocation is
6871
safe.
6972

70-
## Validation
73+
Browser sessions use server-managed HttpOnly cookies. Native Android and Qt
74+
players are separate native-first applications that use protected
75+
`ScreenRig-Pairing`, `ScreenRig-Device`, and `ScreenRig-Session`
76+
authorization. Runtime pages use `screenrig.canvas/v1`; protected content and
77+
`screenrig.webapp-package/v1` artifacts remain manifest-bound. Screenshotting
78+
is not part of v1.
79+
80+
## Artifact provenance and validation
81+
82+
`components.lock.json` pins the exact `screenrig/cli` commit, artifact
83+
filename, and SHA-256 used to generate `plugins/screenrig`. Root skill and
84+
metadata files are canonical; the committed plugin directory is generated and
85+
must not be edited independently. CI reproduces the pinned CLI artifact,
86+
rebuilds/validates the bundle, scans the public boundary, and publishes
87+
deterministic `screenrig-plugin.tar.gz`.
88+
89+
This repository does not deploy ScreenRig. Production assembly is owned only by
90+
the backend component lock.
7191

7292
```sh
7393
python3 scripts/check-public-repo.py
7494
skills/screenrig/scripts/screenrig --json version
7595
```
7696

77-
Security reports belong in
78-
[GitHub Private Vulnerability Reporting](https://github.com/screenrig/plugin/security/advisories/new),
79-
not in public issues. See [SECURITY.md](SECURITY.md).
97+
Full regeneration additionally requires the exact CLI artifact selected by
98+
`components.lock.json`. Source validation does not prove marketplace
99+
installation, automatic enrollment against the live API, pairing, public
100+
browser handoff, native hardware, or production deployment.
80101

81-
This repository is licensed under Apache-2.0. The license applies to this
82-
public plugin and its bundled Apache-2.0 CLI; it does not license other
83-
ScreenRig services or repositories.
102+
Security reports belong in
103+
[GitHub Private Vulnerability Reporting](https://github.com/screenrig/plugin/security/advisories/new).
104+
See [SECURITY.md](SECURITY.md). The Apache-2.0 license covers this public plugin
105+
and its bundled CLI, not other ScreenRig services or repositories.

‎components.lock.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,10 @@
33
"state": "resolved",
44
"cli": {
55
"repository": "screenrig/cli",
6-
"commit": "35409abcc863c85096a20fee801e8bcb58a2a39f",
6+
"commit": "15dd77ca7a97d82187c91c66cb0a505be64467e9",
77
"artifact": {
88
"file": "screenrig-cli.tgz",
9-
"sha256": "a27cfcd812f295ca62960282e0a4f76bc76ab608d341ee823aaf4088d5936121"
9+
"sha256": "ec9fdc8f1755d2ceb530c05d30375ed91098931acdbc16292b99d8932db432ec"
1010
}
1111
}
1212
}

‎plugins/screenrig/README.md‎

Lines changed: 67 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# ScreenRig agent plugin
22

3-
ScreenRig is an agent-first digital-signage and kiosk workflow. The canonical
4-
public marketplace source is
5-
[github.com/screenrig/plugin](https://github.com/screenrig/plugin).
3+
ScreenRig is an agent-first digital-signage workflow. This public repository is
4+
the canonical marketplace source and distributes one generated plugin containing
5+
the ScreenRig skill plus a pinned CLI artifact.
66

77
## Install
88

@@ -20,64 +20,86 @@ codex plugin marketplace add https://github.com/screenrig/plugin.git --ref main
2020
codex plugin add screenrig@screenrig --json
2121
```
2222

23-
Then open the [ScreenRig Player](https://play.screenrig.ai) and ask your agent
24-
to pair the six-character code, or paste a public
25-
`https://screenrig.ai/ABC-234` setup instruction into the agent. Do not look
26-
for or install a global `screenrig` binary: the plugin's skill invokes its
27-
pinned, bundled CLI.
23+
Confirm the installed entry and read its package root:
2824

29-
This distributable contains the ScreenRig skill and its pinned, bundled CLI.
30-
The CLI requires Node.js 20.11 or newer. The wrapper resolves only the bundled
31-
CLI; it does not download or execute a mutable command at runtime. Agent
32-
workflows use machine-readable output and keep credentials in user-private
33-
application state outside the replaceable plugin directory.
25+
```sh
26+
claude plugin list --json
27+
codex plugin list --json
28+
```
3429

35-
If a newly installed plugin is not loaded into the current agent session, run
36-
`claude plugin list --json` and read the `installPath` for
37-
`screenrig@screenrig`, or run `codex plugin list --json` and read its
38-
`source.path`. Verify that exact installation before continuing:
30+
Run `node --version` first. The package-relative launcher fails closed unless
31+
Node.js 20.11 or newer is active. After installation, use the agent's plugin list
32+
JSON to read the ScreenRig `installPath` (Claude Code) or `source.path`
33+
(Codex), then verify the installed bundle:
3934

4035
```sh
4136
<plugin-root>/skills/screenrig/scripts/screenrig --json version
4237
```
4338

44-
Then use that same package-relative wrapper for ScreenRig commands. Do not add
45-
it to `PATH` or substitute another executable.
39+
Use that same launcher for every ScreenRig command. It resolves only
40+
`<plugin-root>/cli/dist/bin.js`; it does not use a global executable or fetch a
41+
mutable command at runtime.
42+
43+
## Pairing and browser setup
44+
45+
Open `https://play.screenrig.ai` and ask the agent to pair the six-character
46+
code. The browser Player displays a middle dash such as `ABC-234`; the current
47+
default pair command requires the canonical six characters:
48+
49+
```sh
50+
<plugin-root>/skills/screenrig/scripts/screenrig --json screen pair ABC234
51+
```
52+
53+
The public homepage handoff is separate first-use convenience. An unclaimed
54+
`https://screenrig.ai/ABC-234` locator lasts 30 minutes. `browser setup --code
55+
ABC-234` accepts the dashed display form (or `ABC234`), and a successful claim
56+
creates a fresh independent 10-minute protected delivery window. CLI output is
57+
limited to the normalized code, claim status, and fragment-free Player URL.
4658

47-
The first authenticated operation creates a ScreenRig account automatically,
48-
stores its permanent credential with user-only permissions, and resumes the
49-
requested operation. The default file is
59+
The first authenticated operation enrolls automatically, stores its credential
60+
with user-only permissions outside the replaceable plugin directory, verifies
61+
it, and resumes the original request. The default configuration is
5062
`$XDG_CONFIG_HOME/screenrig/config.json` when `XDG_CONFIG_HOME` is set,
5163
`%APPDATA%\screenrig\config.json` on Windows, or
52-
`~/.config/screenrig/config.json` otherwise. `SCREENRIG_CONFIG` may select a
53-
different path. Uninstalling or upgrading the plugin does not remove this user
54-
configuration.
55-
56-
The canonical customer command is `screen pair CODE [--label LABEL]`. The
57-
plugin also supports implemented application, playlist, media, screen, event,
58-
and application K/V operations documented by the bundled skill.
59-
60-
Credential removal is explicit and server-first. `screenrig auth revoke --yes`
61-
revokes exactly the stored calling credential, issues no replacement, and
62-
removes local credential, enrollment, and transient authenticated-operation
63-
state only after the server confirms an empty `204` response. Non-secret API
64-
configuration is preserved. The account, screens, and content remain, but the
65-
revoked credential cannot be recovered in the current anonymous no-email
66-
model; the next account-scoped command enrolls a separate new account. Failed
67-
or ambiguous requests retain local state, and retrying the exact revocation is
64+
`~/.config/screenrig/config.json`; `SCREENRIG_CONFIG` may override it.
65+
66+
`auth revoke --yes` revokes the calling credential on the server before local
67+
credential and retry state are removed. Success requires an empty `204`
68+
response and issues no replacement. The account, screens, and content remain;
69+
the next account-scoped command enrolls a separate new account. Failed or
70+
ambiguous results preserve local state, and retrying the exact revocation is
6871
safe.
6972

70-
## Validation
73+
Browser sessions use server-managed HttpOnly cookies. Native Android and Qt
74+
players are separate native-first applications that use protected
75+
`ScreenRig-Pairing`, `ScreenRig-Device`, and `ScreenRig-Session`
76+
authorization. Runtime pages use `screenrig.canvas/v1`; protected content and
77+
`screenrig.webapp-package/v1` artifacts remain manifest-bound. Screenshotting
78+
is not part of v1.
79+
80+
## Artifact provenance and validation
81+
82+
`components.lock.json` pins the exact `screenrig/cli` commit, artifact
83+
filename, and SHA-256 used to generate `plugins/screenrig`. Root skill and
84+
metadata files are canonical; the committed plugin directory is generated and
85+
must not be edited independently. CI reproduces the pinned CLI artifact,
86+
rebuilds/validates the bundle, scans the public boundary, and publishes
87+
deterministic `screenrig-plugin.tar.gz`.
88+
89+
This repository does not deploy ScreenRig. Production assembly is owned only by
90+
the backend component lock.
7191

7292
```sh
7393
python3 scripts/check-public-repo.py
7494
skills/screenrig/scripts/screenrig --json version
7595
```
7696

77-
Security reports belong in
78-
[GitHub Private Vulnerability Reporting](https://github.com/screenrig/plugin/security/advisories/new),
79-
not in public issues. See [SECURITY.md](SECURITY.md).
97+
Full regeneration additionally requires the exact CLI artifact selected by
98+
`components.lock.json`. Source validation does not prove marketplace
99+
installation, automatic enrollment against the live API, pairing, public
100+
browser handoff, native hardware, or production deployment.
80101

81-
This repository is licensed under Apache-2.0. The license applies to this
82-
public plugin and its bundled Apache-2.0 CLI; it does not license other
83-
ScreenRig services or repositories.
102+
Security reports belong in
103+
[GitHub Private Vulnerability Reporting](https://github.com/screenrig/plugin/security/advisories/new).
104+
See [SECURITY.md](SECURITY.md). The Apache-2.0 license covers this public plugin
105+
and its bundled CLI, not other ScreenRig services or repositories.

0 commit comments

Comments
 (0)