Sharing results with Phi (cockpit-share)
How to publish results, videos, and reports to Phi's Artifacts page.
When you have a result that the owner (Phi) needs to look at, you must publish it using cockpit-share. This applies to any visual or structured result: an HTML page or site, a report, a screenshot, a PDF, a video, or a CSV. You must never just say "it's on the Desktop" or give a local file path. Instead, you must publish the files and give him the link.
Commands
Use the cockpit-share command to publish a file or a folder. You must always provide your conversation name and a title.
URL=$(cockpit-share report.html --from "<your conversation name>" --title "Weekly Report")
The command prints the URL, which looks like https://maximind.dev/a/<id>. You can also use these options:
--keep <days>: Keep the artifact for up to 30 days.--note "<text>": Add a short note about the result.--entry <file>: Set the main file when uploading a folder (e.g.,--entry index.html).--pdf: Make an A4 PDF at once for printing.--state-key <name>: Name the page's saved state (ticks, progress) so a new publish of the same page keeps it. See "Videos and saved ticks inside a page".--raw: Upload videos as they are, without converting them (.movfiles still need converting).--dry-run: Check if the upload would be accepted without actually uploading.--json: Get the output as JSON.
You can view your published artifacts with cockpit-share list, and delete one with cockpit-share delete <id>.
What happens
Before uploading, your Mac converts videos to H.264 MP4 with the built-in avconvert (every .mov, and .mp4 files over 40 MB) and makes a thumbnail with qlmanage. The files then go straight from your Mac to private storage. On the server, a single picture is converted to WebP.
The resulting link https://maximind.dev/a/<id> requires Phi's admin sign-in. Only he can open it unless he creates a share link. The result will immediately appear on his Cockpit Artifacts page and as a clickable chip directly in your chat.
Rules
- Report the link: Always put the URL in your task update, like
org-task done <id> "…" --link <URL>, and include it in your chat reply. - Expiry: Links expire after 30 days. Only Phi can choose to keep them longer.
- No secrets: Never publish secrets. Files like
.env, keys, and credentials are automatically refused by the CLI. Never try to work around a refusal. - Limits: 500 MB maximum per file. 1 GB and 400 files maximum per result. Each conversation can publish up to 100 results and 3 GB per day.
- Allowed types:
html,htm, site assets (css, js, pictures, fonts, etc. inside a folder), pictures (png,jpg,jpeg,webp,gif), documents (pdf,md,txt,csv,json), video (mp4,m4v,webm,mov), audio (mp3,m4a,wav), andziparchives. - HTML sandboxing: HTML runs in a sandbox with no cookies and no login access. If you upload a folder site, use relative links and ensure there is an
index.htmlentry.
Codex
If you are running as Codex, you must run cockpit-share outside the sandbox, just like cockpit-msg. It requires network access and the Mac's Keychain to read the Cockpit key.
Troubleshooting
- "no Cockpit key": Ask Phi to provide or configure the key.
- HTTP 429: You hit the daily cap for artifacts.
- "looks like secrets": The file triggered the secrets scanner. Remove the file or the sensitive contents.
- Video conversion failed: use
--rawfor an.mp4; convert a.movto.mp4first.
How to make a good artifact
- Put the decision first. Start with one
> [!DECISION]callout saying exactly what Phi must decide or reply (e.g., "Reply OK to send..."). Then the summary, then the details. - Choose the right format. Use markdown for reports, drafts, approvals, and lists (the template makes it look designed). Use HTML for interactive things, layouts, charts, or a page that must look exactly like the real product. Use a PDF for documents that will be printed or sent on.
- Design for phones. Keep tables to 4 columns or fewer. Split wider tables or use a list. Keep paragraphs short and put headings every few screens. Do not use huge images.
- Do not repeat the title. The template shows it, so do not use an
# h1for the title. Use--titlefor a clear Vietnamese title Phi understands. - Make one artifact per decision. Attach it to the ask (
--attach). Use--pdfwhen Phi may print it. - Write in Vietnamese for Phi. Use southern, plain Vietnamese when the content is for him. Keep English for code and technical terms.
- Example markdown file:
> [!DECISION]
> Anh chốt phương án này nha. Reply OK để em tiến hành.
## Chi tiết
| Hạng mục | Số lượng | Ghi chú |
| --- | --- | --- |
| Server | 1 | Chạy 24/7 |
| Domain | 1 | Gia hạn 1 năm |
## Việc cần làm
- [x] Soạn báo giá
- [ ] Gửi cho khách
> [!WARNING]
> Phải gia hạn trong tuần này.
Let Phi decide and reply from the page
Phi can answer a result without leaving it. The viewer has a Trả lời box and, when the page lists decisions, one tap per item: Theo đề xuất, Không or Ý khác…. An item without your recommendation has nothing to agree with, so it only takes his own words (ý khác). His answer comes back to your conversation (or to the conversation that took over from you after a renewal), as a normal message:
[Phi trả lời kết quả: <title> · https://maximind.dev/a/<id>]
Quyết định: 1 ✓, 2 ✓, 3 Không, 4 ý khác (✓ = đồng ý theo đề xuất)
Mục 4: <what he wrote for item 4>
Ghi chú: <his note>
✓ means he took your recommendation for that item; it only appears on items you recommended. Act on it, and report back on the task as usual.
So that the viewer finds your decisions, write them one of two ways:
- Markdown: a heading such as
## Anh cần quyết định(orWhat Phi needs to decide), followed by a numbered list, one decision per item. End an item with**Đề xuất**(orRecommended) when you recommend it. An open question without a recommendation is fine: write it plainly ("chưa có đề xuất" is read as no recommendation) and put the options in the item itself, not on another page. - HTML: mark each decision with attributes. Then the order and wording are exact:
<ol>
<li data-decision-id="test-scope" data-recommended>Bài kiểm tra kiểu CELTA chỉ thay nửa TESOL.</li>
<li data-decision-id="start-month" data-decision-label="Tháng 11 là tháng thử">…</li>
</ol>
Keep each item to one clear choice, with a short label of a sentence or two, at most 20 items per page. Put the decisions at the top of the page.
Videos and saved ticks inside a page
An HTML result runs in a sandbox: it has no storage (localStorage throws), and an embedded YouTube player does not start there. Do not try to work around that. Ask the viewer around your page instead. Every HTML page you publish gets a small helper, window.MaxiMind, for this.
A video. Write a normal link and mark it. In the viewer it plays in an overlay on the same page; anywhere else it is still a link that opens YouTube.
<a data-mm-video href="https://www.youtube.com/watch?v=VIDEO_ID&t=1m30s" target="_blank" rel="noopener">Bài 1: bấm hợp âm Em</a>
From script, call MaxiMind.video("VIDEO_ID", {start: 90}) inside a click handler. YouTube only, one video at a time. Never embed a YouTube <iframe> in the page itself.
Saved state (a daily tick list, progress, a choice). One JSON value of up to 64 KB per page and per person. It is stored on the server, so it follows Phi from one device to the next.
<label><input type="checkbox" data-tick="d1"> Ngày 1</label>
<label><input type="checkbox" data-tick="d2"> Ngày 2</label>
<script>
const ticks = {};
const paint = () => document.querySelectorAll("[data-tick]").forEach(el => { el.checked = !!ticks[el.dataset.tick]; });
const load = () => window.MaxiMind?.state.get().then(s => { Object.assign(ticks, s.value || {}); paint(); }).catch(() => {});
load();
document.addEventListener("visibilitychange", () => { if (!document.hidden) load(); }); // ticked on another device meanwhile
document.querySelectorAll("[data-tick]").forEach(el => el.addEventListener("change", () => {
const key = el.dataset.tick, on = el.checked;
ticks[key] = on;
window.MaxiMind?.state.update(value => ({ ...value, [key]: on })) // re-reads, applies your change, retries if another device wrote first
.then(s => { Object.assign(ticks, s.value); paint(); })
.catch(() => {}); // no viewer or no state: the tick lasts until the page closes
}));
</script>
MaxiMind.state.get()resolves{value, revision}(valueisnullbefore the first save).MaxiMind.state.update(fn)is the safe way to change it: it reads the stored value, appliesfn, and saves; if another device saved in between, it reads again and re-applies.MaxiMind.state.set(value)replaces the whole value. If the stored value changed since you last read it, it rejects witherror.code === "conflict"and gives youerror.valueanderror.revision.- Every call rejects with
error.codewhen it cannot work:unavailable(no viewer, or this viewer has no state),too_large,rate_limited(30 saves a minute),offline. Always keep the page usable without it. await MaxiMind.readygives the list of what this viewer offers (["video", "state"],["video"]or[]);MaxiMind.has("state")checks one.
Keep the ticks when you publish again. Each publish gets a new link, and by default state belongs to that one link. Give the page a stable name and every later publish with the same name picks the state up:
cockpit-share guitar/ --entry index.html --from "<your conversation name>" --title "Lộ trình guitar" --state-key guitar-phi
The name (a–z, 0–9, dot, dash, underscore; up to 63 characters) belongs to your conversation on your Mac from its first use. A publish with the same name from another Mac or under another conversation name is refused, so pick a name that says whose page it is. Store only what the page needs: no secrets, nothing private that Phi did not put there himself.
Who gets what. Phi, signed in on the web viewer: videos and state. Staff opening a result from a Workplace task, and visitors with a share link: videos only. The iPhone app's native view: neither yet, so the link opens YouTube and ticks are not saved there. That is why the page must work without the helper.