From a4cb80b6d08e5c2423851874a81adc3921cce86e Mon Sep 17 00:00:00 2001 From: Talos Kernel Date: Wed, 7 Oct 2026 23:54:45 +0000 Subject: [PATCH] docs: add first-task recipes and reproducible proof demos --- .github/ISSUE_TEMPLATE/first_run.yml | 76 ++++++++++++++++ .github/workflows/ci.yml | 3 + CONTRIBUTING.md | 9 ++ README.md | 5 ++ docs/first-task.md | 124 +++++++++++++++++++++++++++ scripts/demo-proof.py | 63 ++++++++++++++ 6 files changed, 280 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/first_run.yml create mode 100644 docs/first-task.md create mode 100644 scripts/demo-proof.py diff --git a/.github/ISSUE_TEMPLATE/first_run.yml b/.github/ISSUE_TEMPLATE/first_run.yml new file mode 100644 index 0000000..4f0f1c1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/first_run.yml @@ -0,0 +1,76 @@ +name: First install or first task +description: Share a working checkpoint or an installation blocker; no coding required. +title: "[First run] " +labels: [documentation] +body: + - type: markdown + attributes: + value: | + Thank you for trying Talos. A failed or blocked attempt is useful feedback too. + Try https://github.com/talos-kernel/Talos/blob/main/docs/first-task.md if you need a small task. + This report is PUBLIC. Never attach credentials, OAuth files, talos.env, full event logs, + personal paths, private hosts or customer data. Report security vulnerabilities privately: + https://github.com/talos-kernel/Talos/security/advisories/new + - type: input + id: version + attributes: + label: Talos version or source commit + description: Use talos version; if installation failed before that, say not installed. + validations: + required: true + - type: input + id: platform + attributes: + label: OS, architecture and Python version + placeholder: "Example: Debian, x86_64, Python 3.11 — no hostname needed" + validations: + required: true + - type: dropdown + id: install + attributes: + label: Installation method + options: + - Signed installer + - Source checkout + - Pinokio + - macOS app + - Other (describe below) + validations: + required: true + - type: dropdown + id: checkpoint + attributes: + label: Furthest checkpoint reached + options: + - Installation blocked + - Installed, setup blocked + - Setup complete, model request failed + - Received a model answer + - Wrote and independently checked the trial note + validations: + required: true + - type: textarea + id: result + attributes: + label: What worked, what failed, and what you checked + description: Include exact steps, expected and actual result, and any manual corrections. Positive feedback is not required. + validations: + required: true + - type: input + id: model + attributes: + label: Provider and model (optional) + description: Names only; no API keys, account identifiers or private endpoint URLs. + - type: textarea + id: excerpt + attributes: + label: Short redacted error excerpt (optional) + description: Review manually before posting. Do not paste full doctor output, configuration or logs. + render: text + - type: checkboxes + id: privacy + attributes: + label: Before publishing + options: + - label: I removed secrets, personal paths, private hosts and customer data from this public report. + required: true diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 40e42c4..e2ac92b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -60,6 +60,9 @@ jobs: - name: Check FAQ search metadata and links run: python scripts/check-site-discovery.py + - name: Run offline proof demonstrations + run: python scripts/demo-proof.py + - name: Verify embedded signature-verifier pins run: python scripts/sync-verifier-lock.py --check diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d427382..c037afb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,11 @@ anything security-relevant — it states the scope and the limits no patch will ## Set up +You do not need to write code to help. Follow the [first-task guide](docs/first-task.md) +and [report the first checkpoint that worked or failed](https://github.com/talos-kernel/Talos/issues/new?template=first_run.yml). +A reproducible installation blocker is useful feedback. Keep all public reports free +of credentials, personal paths, private endpoints and full logs. + Fork the repository on GitHub, then clone your fork. Keeping the canonical repository as `upstream` makes it possible to rebase without mixing your work with release commits: @@ -37,6 +42,10 @@ python -m talos --once # one real cycle, after wiring anything new python -m talos doctor # what this machine is missing — changes nothing ``` +For a small, offline introduction to the existing tests, run +`python scripts/demo-proof.py`. It checks three fixture groups without calling a model; +it does not replace the full suites or prove a real conversation succeeded. + ## Where a first contribution belongs The kernel is deliberately hard to change (see below). The rewarding first work is in the diff --git a/README.md b/README.md index 6e1f13c..80d3b87 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,11 @@ operation or a substitute for reviewing permissions and keeping backups. [Watch a recorded session](https://talos-agent.ch/console.html) · [Install with Pinokio](https://github.com/talos-kernel/talos-pinokio) +**New to Talos?** [Try three small, checkable tasks](docs/first-task.md): turn notes into +a handover, save and read back a local note, and compare release notes without inventing +missing facts. Already tried it? [Share your first-run result](https://github.com/talos-kernel/Talos/issues/new?template=first_run.yml), +including installation blockers. No star or positive review required. + ## Is Talos right for you? - **Run local models:** connect Ollama on hardware you control, or use a configured cloud provider. diff --git a/docs/first-task.md b/docs/first-task.md new file mode 100644 index 0000000..bfaa958 --- /dev/null +++ b/docs/first-task.md @@ -0,0 +1,124 @@ +# Your first useful task with Talos + +Try a small job with a result you can inspect. These three recipes use only fictional +data. They are **instructions to reproduce**, not transcripts, benchmarks or claims +that every model will succeed. Keep real customer data and credentials out of a trial. + +New here? Start with the [installation guide](../README.md#install) and the +[model, cost and permission FAQ](https://talos-agent.ch/faq/). Use your existing model +connection; provider usage may cost money. No new gateway subscription is required. + +## Before the first conversation + +In your installation directory, using its Python environment: + +```bash +python -m talos version +python -m talos doctor +python -m talos chat +``` + +If setup is incomplete, run `python -m talos setup terminal` first. This configures the +local identity and model; it is not necessary to create a Telegram bot. With the signed +installer, use the `bin/talos` commands printed at the end of installation instead. +Do not configure a second Telegram poller beside an existing service. + +Use an attended terminal for these tasks. Each prompt below is deliberately one line: +`talos chat` submits each newline as a separate turn. Paste one prompt, then wait for +the result before starting the next. `talos ask`, redirected output and background +runs cannot collect interactive approvals. Resolve relevant doctor findings; do not +turn off sandboxing or loosen policy to make a demonstration pass. + +## 1. Turn rough notes into a useful handover + +Paste this into the chat: + +```text +Turn these fictional meeting notes into a short handover with three columns: action, owner, due date. Answer here only; do not use tools or write files. Notes: Rowan owns the draft and will finish it on 12 November 2026. Casey will review the draft on 13 November 2026. The launch date has not been decided. No owner was assigned to launch planning. Do not invent missing dates or owners. +``` + +**Check the result:** Rowan / draft / 12 November; Casey / review / 13 November; +launch owner and date explicitly unknown. This checks a useful model response, not +the permission kernel. No tool should have run. + +## 2. Save a local note, then verify the actual file + +Use a fresh filename if this example already exists. Paste: + +```text +Create workspace/first-task-note.md only if it does not already exist. Its exact content must be two lines, with a newline after each. The first line is "# Trial handover" and the second is "Draft: Rowan. Review: Casey. Launch: undecided."; omit the enclosing quotation marks. Use file tools only, no shell or network. Read the file back after writing. Report the real tool outcome; do not claim success if the write or read failed. If the file already exists, stop without changing it. +``` + +Review any kernel-generated approval before answering it. An ordinary reversible +workspace write may already be allowed at your configured autonomy level; an approval +dialogue is **not** promised for every write. Do not choose a broader permission just +to reproduce this recipe. + +**Check the result independently:** open `workspace/first-task-note.md` in your editor. +It must contain exactly the two requested lines. Repeating the prompt must leave the +existing file unchanged. A reply saying “saved” is not evidence on its own. +Keep the harmless note or remove that specific file yourself after inspecting it. + +## 3. Compare two changes without inventing a launch claim + +Paste: + +```text +Compare these fictional release notes. Answer here only, with no tools. Before: CSV export is available. Scheduled reports are not available. After: CSV export remains available. Scheduled reports are now in preview. Known issue: preview reports sometimes arrive twice. Give one unchanged feature, one new feature, one caveat and one check before use. Do not describe preview as production-ready, or claim the duplicate issue is fixed. +``` + +**Check the result:** CSV export is unchanged; scheduled reports are a preview; +duplicate delivery remains a known issue; a practical check should inspect for duplicate +reports before relying on them. This is a model-quality exercise, not a real Talos bug +report or a feature announcement. + +## How approvals fit a longer task + +When Talos actually asks, **Allow once** covers the displayed action. **Allow this task** +covers eligible actions within the current task's enforced scope; it is not approval +for arbitrary future work. Exact-action standing approvals are a separate operator +choice. Hard denials remain denials. See the +[permission FAQ](https://talos-agent.ch/faq/#task-approval) before changing those settings. + +After a tool-backed task, use `python -m talos status` and `python -m talos verify` to +inspect the installation's recorded activity and chain. A valid chain checks consistency +of the records, **not** that the answer was correct or an external side effect succeeded. +It does not protect against an administrator rewriting the entire local chain; see +[the security limits](../SECURITY.md). +Review outputs locally: logs can contain private paths and task content. + +## Reproduce the mechanics without a model account + +For a source checkout with the [development dependencies](../CONTRIBUTING.md#set-up) +installed: + +```bash +python scripts/demo-proof.py +``` + +This runs three labelled groups of existing regression tests: file read/write and +receipts; approval gating, task scope and one-use capabilities; rollback and audit integrity. +The tests use temporary files and controlled runners, with **no model or provider +call**. They are not recordings of the three conversations above, a full installation +test, a live messenger test or a speed comparison. Read the exact selected tests in +[the script](../scripts/demo-proof.py). To run one group: `--case approval`. + +For actual model-backed evidence, run the recipes yourself and record the model, +Talos version, task outcome and any correction needed. Do not publish a staged +terminal animation as a real conversation. + +## Help another person get started + +We are looking for independent first-install feedback on macOS, Linux, Raspberry Pi +and VPS setups. Completing all three tasks is optional: **a blocked install is useful +feedback too**. There is no star, account-upgrade or positive-review requirement. + +[Share a first-run result](https://github.com/talos-kernel/Talos/issues/new?template=first_run.yml) +with your OS, version, install method and which checkpoint worked or failed. +Share only a short, manually redacted excerpt if one is necessary. Never attach +`talos.env`, `.env`, OAuth files, full event logs, private hostnames or personal paths. +For a security vulnerability, use [private reporting](../SECURITY.md), not a public issue. + +Want to build instead? [Fork Talos](https://github.com/talos-kernel/Talos/fork), read +[CONTRIBUTING.md](../CONTRIBUTING.md), and choose a +[small existing issue](https://github.com/talos-kernel/Talos/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). diff --git a/scripts/demo-proof.py b/scripts/demo-proof.py new file mode 100644 index 0000000..a652a30 --- /dev/null +++ b/scripts/demo-proof.py @@ -0,0 +1,63 @@ +#!/usr/bin/env python3 +"""Replay small, existing regression fixtures; never present them as live model runs.""" +from __future__ import annotations + +import argparse +from pathlib import Path +import subprocess +import sys + +ROOT = Path(__file__).resolve().parents[1] +CASES = { + "files": ( + "File read/write and the receipt binding an action to its grant", + ( + "tests/test_tools.py::test_read_file_returns_content", + "tests/test_tools.py::test_write_file_creates_and_writes", + "tests/test_executor.py::test_allowed_write_runs_and_returns_result", + "tests/test_executor.py::test_receipt_names_the_grant_that_authorised_the_run", + ), + ), + "approval": ( + "Explicit task approval, no carryover to the next task, one-use capabilities", + ( + "tests/test_executor.py::test_irreversible_needs_human_and_does_not_run", + "tests/test_capability.py::test_needs_human_without_approval_yields_no_token", + "tests/test_capability.py::test_token_is_single_use", + "tests/test_task_approval_flow.py::test_task_approval_runs_different_actions_until_completion", + "tests/test_task_approval_flow.py::test_once_then_task_keeps_the_original_task_id", + ), + ), + "recovery": ( + "A failed fixture write rolls back; edits to audit records are detected", + ( + "tests/test_executor.py::test_runner_exception_rolls_back", + "tests/test_executor.py::test_verify_failed_rolls_back", + "tests/test_eventlog.py::test_a_fresh_chain_verifies", + "tests/test_eventlog.py::test_editing_an_event_names_its_id", + ), + ), +} + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--case", choices=("all", *CASES), default="all") + args = parser.parse_args() + print("Fixture demonstrations: real Talos components, controlled test runners.\n" + "No model calls. Not a live conversation or performance benchmark.", flush=True) + selected = CASES if args.case == "all" else {args.case: CASES[args.case]} + for name, (description, nodes) in selected.items(): + print(f"\n{name}: {description}", flush=True) + result = subprocess.run( + [sys.executable, "-m", "pytest", "-q", *nodes], cwd=ROOT, check=False, + ) + if result.returncode: + print(f"Fixture group {name} failed; no success claim.", file=sys.stderr) + return result.returncode + print("Selected fixture groups passed. Model-backed recipes still need a real run.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main())