431 lines
36 KiB
Python
431 lines
36 KiB
Python
"""Shared English guide content. Regenerate command docs after editing."""
|
|
|
|
GUIDE = {'start': {'title': 'Start with FrameBridge',
|
|
'sections': [{'heading': 'One interface for people and agents',
|
|
'body': 'FrameBridge provides tools and a shared command-line interface '
|
|
'for human operators and authorized agents. fb is the short name '
|
|
'for framebridge; both run the same program. The tools run on '
|
|
'your Linux computers. The ChatGPT model remains hosted. Read '
|
|
'this guide for the installed version before operating; confirm '
|
|
'the receiver, target and available capabilities. Use the '
|
|
'installed CLI and tools for normal work. Edit software only when '
|
|
'the owner explicitly requests development, using a separate '
|
|
'source clone and reviewable changes rather than rewriting the '
|
|
'installed program.',
|
|
'commands': ['fb help', 'fb status', 'fb --json status']},
|
|
{'heading': 'Install and connect',
|
|
'body': 'On a supported Debian system, install the downloaded package '
|
|
'with the package manager. Normal first connection does not '
|
|
'require a separate setup, doctor or start sequence. Run connect '
|
|
'in a normal interactive terminal. Advanced setup is optional for '
|
|
'selecting central/node roles and public settings.',
|
|
'commands': ['sudo apt install ./FrameBridge-0.3.1.deb', 'fb connect']},
|
|
{'heading': 'Updating and removal',
|
|
'body': 'Install an official update through the normal package manager. '
|
|
'Normal package removal stops package-owned managed processes and '
|
|
'retains the profile and saved encrypted connection material for '
|
|
'deliberate reuse; it is not a credential-forgetting operation. '
|
|
'Use the separately documented explicit forget action first if '
|
|
'that is your intended outcome. Do not assume purge erases '
|
|
'user-profile data.',
|
|
'commands': ['sudo dpkg --remove framebridge-original-expanded']},
|
|
{'heading': 'Human authentication',
|
|
'body': 'The normal connection asks for an optional account label, a '
|
|
'hidden tunnel ID and a hidden MCP server access key. The label '
|
|
'is metadata, not proof of ChatGPT login. Browser login/consent '
|
|
'and normal operating-system authentication remain human actions '
|
|
'in the normal interface. Never put credentials in chat, command '
|
|
'arguments, documentation or example files. A successful managed '
|
|
'connection returns to the prompt and can run independently of '
|
|
'that terminal. Reboot only when an actual system change requires '
|
|
'it.',
|
|
'commands': []},
|
|
{'heading': 'Choose the right guide',
|
|
'body': 'Use commands for the reference, connection and lifecycle for '
|
|
'state changes, nodes for central/node work, terminals for '
|
|
'persistent Bash, and screens for authentic CUA evidence. Query '
|
|
'success alone does not mean the connection is ready. The guide '
|
|
'describes registered operations; use status/doctor to '
|
|
'investigate current state.',
|
|
'commands': ['fb help commands',
|
|
'fb help connection',
|
|
'fb help lifecycle']}]},
|
|
'commands': {'title': 'Command reference',
|
|
'sections': [{'heading': 'Everyday commands',
|
|
'body': 'connect establishes or resumes the managed ChatGPT '
|
|
'connection. disconnect pauses that connection until an '
|
|
'explicit connect, including across recovery and reboot. '
|
|
'status reports runtime, connection, intended connection state '
|
|
'and boot policy. doctor diagnoses prerequisites/problems. '
|
|
'setup edits advanced stopped-profile settings. console opens '
|
|
'the text work view. help reads this versioned reference.',
|
|
'commands': ['fb connect',
|
|
'fb disconnect',
|
|
'fb status',
|
|
'fb status connection',
|
|
'fb status runtime',
|
|
'fb status boot',
|
|
'fb status console',
|
|
'fb doctor',
|
|
'fb setup',
|
|
'fb console',
|
|
'fb help']},
|
|
{'heading': 'Services and boot',
|
|
'body': 'For an already configured managed profile, service start/stop '
|
|
'control the current stack symmetrically. Boot enable/disable '
|
|
'changes future startup policy without stopping current work '
|
|
'or forgetting the saved credential. First node provisioning '
|
|
'is an explicit exception described in lifecycle. Without '
|
|
'managed setup, non-node service start starts local tools '
|
|
'only; normal first connection should use connect. Read status '
|
|
'before and after changes. The separate credentials forget '
|
|
'action is destructive and requires explicit confirmation.',
|
|
'commands': ['fb service start',
|
|
'fb service stop',
|
|
'fb service boot enable',
|
|
'fb service boot disable']},
|
|
{'heading': 'Console and specialized operations',
|
|
'body': 'console login manages optional work-view opening after an '
|
|
'authenticated tty1 login; it does not enable automatic login. '
|
|
'tty service manages the terminal daemon; tty list lists '
|
|
'sessions. nodes, certificates and screen-access retain their '
|
|
'domain-specific subcommands. Use --help at the relevant '
|
|
'command for its exact arguments. Avoid compatibility aliases '
|
|
'in new automation.',
|
|
'commands': ['fb console login status',
|
|
'fb tty service status',
|
|
'fb tty list',
|
|
'fb nodes --help',
|
|
'fb certificates --help',
|
|
'fb screen-access --help']},
|
|
{'heading': 'Human and structured output',
|
|
'body': 'Use explicit commands in automation rather than the '
|
|
'interactive no-argument menu. --json selects structured '
|
|
'output for an agent; examine operation success, readiness and '
|
|
'state separately. Read errors and the exit status. If human '
|
|
'interaction is required, complete it in the normal '
|
|
'terminal/interface rather than attempting to supply a secret '
|
|
'through the agent. CLI JSON uses an envelope with '
|
|
'schema_version, product, version, command, ok and result. '
|
|
'Read runtime, connection and boot truth inside result; '
|
|
'envelope ok denotes request success. Exit 0 means successful '
|
|
'query/operation, not necessarily a connected transport; exit '
|
|
'1 reports operation/diagnostic failure, exit 2 invalid '
|
|
'arguments or required human interaction/confirmation, and '
|
|
'exit 130 cancellation.',
|
|
'commands': ['framebridge --json status',
|
|
'fb --json status connection']}]},
|
|
'connection': {'title': 'Connect and disconnect ChatGPT',
|
|
'sections': [{'heading': 'Normal managed connection',
|
|
'body': 'connect creates the default standalone profile when absent '
|
|
'and establishes managed startup. It asks for initial human '
|
|
'input in the terminal, checks progress, reports readiness '
|
|
'or an actionable failure, and returns to the prompt. Valid '
|
|
'saved setup can be resumed without repeating the initial '
|
|
'fields. The MCP access key is not an OpenAI API key. Keep '
|
|
"the browser's ChatGPT account login and consent separate "
|
|
'from the optional local account label.',
|
|
'commands': ['fb connect', 'fb status connection']},
|
|
{'heading': 'Saved credentials and next boot',
|
|
'body': 'Managed startup uses protected, host-bound encrypted '
|
|
'connection material. The normal terminal does not have to '
|
|
'remain open. This is a persistence feature, not a promise '
|
|
'that an account, network or tunnel service can never fail. '
|
|
'Connection intent and boot policy are separate: enabled '
|
|
'startup runs the stack at boot, while an intentional '
|
|
'disconnected state remains disconnected until connect.',
|
|
'commands': ['fb status boot', 'fb status']},
|
|
{'heading': 'Intentional disconnect',
|
|
'body': 'disconnect keeps local tools and saved material, but '
|
|
'records the intention to stay disconnected across worker '
|
|
'recovery and reboot. Explicit connect clears that pause. '
|
|
'Check the returned state rather than interpreting a '
|
|
'successful query as an active transport.',
|
|
'commands': ['fb disconnect', 'fb status connection']},
|
|
{'heading': 'Replacement and temporary foreground mode',
|
|
'body': 'Use connect --replace only when deliberately replacing the '
|
|
'account label/tunnel/access configuration. The advanced '
|
|
'--foreground mode is temporary, needs a ready local runtime '
|
|
'and occupies its terminal until interrupted; it is not the '
|
|
'normal managed workflow. Do not use advanced mode merely to '
|
|
'recover a normal saved connection.',
|
|
'commands': []}]},
|
|
'lifecycle': {'title': 'Services, connection intent and boot policy',
|
|
'sections': [{'heading': 'Separate states',
|
|
'body': 'FrameBridge distinguishes actual local runtime, desired '
|
|
'connection, verified transport, boot enablement and saved '
|
|
'credential presence. A healthy runtime can be intentionally '
|
|
'disconnected; a service can be active while disabled for the '
|
|
'next boot. Read the labelled status fields together.',
|
|
'commands': ['fb status', 'fb --json status']},
|
|
{'heading': 'Current managed stack',
|
|
'body': 'For an already configured managed profile, service start and '
|
|
'service stop use the same current-stack boundary without '
|
|
'changing boot enablement. Stop ends current managed work and '
|
|
'transport but keeps profile, boot policy and saved material. '
|
|
'Startup on the next boot follows the retained policy and '
|
|
'intended connection state. A non-node profile without '
|
|
'managed setup starts only local tools. Stopping a terminal '
|
|
'service or session can interrupt its running work.',
|
|
'commands': ['fb service start', 'fb service stop']},
|
|
{'heading': 'Future boot policy',
|
|
'body': 'Once managed setup exists, service boot enable/disable '
|
|
'changes unit enablement only. It does not immediately stop '
|
|
'or start current work and does not delete saved connection '
|
|
'material. Initial node provisioning is described separately '
|
|
'below. Explicitly forgetting saved material is a separate '
|
|
'destructive operation. Legacy autostart disable has its old '
|
|
'broader destructive behavior; use the canonical service boot '
|
|
'commands for new workflows.',
|
|
'commands': ['fb service boot enable',
|
|
'fb service boot disable',
|
|
'fb status boot']},
|
|
{'heading': 'First managed startup for a node',
|
|
'body': 'After advanced node setup and the required '
|
|
'enrollment/approval, a node without a managed installation '
|
|
'can run service start in a normal terminal. This first call '
|
|
'creates managed startup, enables future boot and starts the '
|
|
'node now; the result explicitly reports '
|
|
'initial_configuration and boot_policy_changed. '
|
|
'Alternatively, first service boot enable prepares and '
|
|
'enables the node unit without starting current work. Initial '
|
|
'preparation can require normal owner authentication and is '
|
|
'not silently performed by an unattended JSON request. Once '
|
|
'configured, the ordinary start/stop and boot-policy-only '
|
|
'contracts apply. A node does not need its own ChatGPT '
|
|
'tunnel.',
|
|
'commands': ['fb service start',
|
|
'fb service boot enable',
|
|
'fb status boot']},
|
|
{'heading': 'Console opening',
|
|
'body': 'Opening console is a view operation, separate from Linux '
|
|
'service startup. Optional console login enable/disable '
|
|
'changes the owned startup hook after an authenticated tty1 '
|
|
'Bash login. This hook does not bypass normal login. Review '
|
|
"the command's scope before changing it.",
|
|
'commands': ['fb console login status']}]},
|
|
'nodes': {'title': 'Central and node operation',
|
|
'sections': [{'heading': 'Roles',
|
|
'body': 'Standalone provides local tools. Central adds the broker for '
|
|
'enrolled nodes. A node joins one selected central instance and '
|
|
'uses its ChatGPT connection; it does not need another ChatGPT '
|
|
'tunnel or phone pairing. Advanced setup selects the role. '
|
|
'Preserve explicit authenticated node transport and real identity '
|
|
'approval.',
|
|
'commands': ['fb setup', 'fb nodes --help']},
|
|
{'heading': 'Enrollment is not availability',
|
|
'body': 'Enrollment submission, central approval, node receipt of '
|
|
'authorization and a running node agent are separate stages. '
|
|
'status reports what it actually knows; an unchecked agent is not '
|
|
'evidence that the node is online. Central list/pending/approve '
|
|
'and node enroll/poll/status/run have role-specific purposes. '
|
|
'poll can complete saved authorization; it is not a purely '
|
|
'observational operation. After enrollment, consult the lifecycle '
|
|
'topic for first managed node startup and its explicit initial '
|
|
'boot-policy effect.',
|
|
'commands': ['fb nodes list', 'fb nodes pending', 'fb nodes status']},
|
|
{'heading': 'Targets',
|
|
'body': 'LOCAL means the actual receiving machine. Use enrolled, '
|
|
'confirmed aliases or IDs and inspect the selected target before '
|
|
'work. Do not guess SSH identities or use historical lab '
|
|
'hostnames as defaults. CLI tty --node can use the authenticated '
|
|
'node transport. The interactive console command is local; run it '
|
|
'at the destination or use an explicitly configured SSH '
|
|
'destination.',
|
|
'commands': []},
|
|
{'heading': 'Transport trust',
|
|
'body': 'certificates create manages a private central/node transport CA, '
|
|
'not a public website certificate or ChatGPT account '
|
|
'authentication. Private keys stay protected on the central host; '
|
|
'distribute only the required public trust material. Off-loopback '
|
|
'broker use requires correctly configured verified TLS. Do not '
|
|
'recreate trust merely to work around a connection symptom.',
|
|
'commands': ['fb certificates --help']}]},
|
|
'terminals': {'title': 'Persistent Bash terminals',
|
|
'sections': [{'heading': 'Service and sessions',
|
|
'body': "tty service controls the profile's terminal daemon. tty open "
|
|
'creates a real Bash session and returns its identifier. Use '
|
|
'that identifier for subsequent observations and input. The '
|
|
'same Bash preserves directory, variables and work between '
|
|
'requests while the session/service remains alive. It does '
|
|
'not preserve running processes across an operating-system '
|
|
"reboot. Tool jobs use a profile-specific HOME; a job's home "
|
|
'directory can therefore differ from the human login home. '
|
|
"Commands retain the connecting account's normal "
|
|
'operating-system permissions.',
|
|
'commands': ['fb tty service status', 'fb tty list', 'fb tty open']},
|
|
{'heading': 'Observe, type and keys',
|
|
'body': 'tty observe returns terminal transcript text, cursor, '
|
|
'dimensions and process state; it is not an authentic '
|
|
'full-screen image. tty type sends text without automatically '
|
|
'adding Enter, though supplied newlines can affect execution. '
|
|
'tty key accepts exact uppercase names such as ENTER and '
|
|
'CTRL_C. Replace session arguments with an identifier '
|
|
'returned by open/list; never guess one.',
|
|
'commands': ['fb tty key --help',
|
|
'fb tty type --help',
|
|
'fb tty observe --help']},
|
|
{'heading': 'Lifetime and closing',
|
|
'body': 'Default real idle expiry is disabled, but a profile can '
|
|
'configure a timeout. Global status/list does not refresh '
|
|
"each session's per-session activity. close destroys a "
|
|
'session rather than merely separating a viewer. Graceful '
|
|
'service stop attempts to close its sessions; elevated or '
|
|
'unverifiable process state can prevent cleanup. Inspect the '
|
|
'outcome instead of assuming that all child processes '
|
|
'disappeared.',
|
|
'commands': ['fb tty close --help', 'fb tty resize --help']},
|
|
{'heading': 'Sudo mode',
|
|
'body': "A session's sudo on/off controls normal privilege "
|
|
'eligibility; it does not log in as root or bypass '
|
|
'operating-system authentication. Changing the mode recreates '
|
|
'Bash, preserving directory and dimensions but not shell '
|
|
'variables or internal state. Authentication stays in the '
|
|
'normal human terminal/interface. Never send a password '
|
|
'through type or chat.',
|
|
'commands': ['fb tty sudo --help']},
|
|
{'heading': 'Work console panels',
|
|
'body': 'console combines an ordinary Bash pane with a read-only '
|
|
'FBTERM activity dashboard. The dashboard is not a second '
|
|
'interactive shell. The tmux prefix is Ctrl+B: release both '
|
|
'keys, then press lowercase z to enlarge/restore a pane, or '
|
|
'lowercase o to switch panes. The release accepts common '
|
|
'zoom-key variants within its dedicated console. Closing a '
|
|
'viewer normally leaves its tmux session alive; leaving Bash, '
|
|
'killing its server or rebooting is different. In a desktop '
|
|
'terminal the shared work view is horizontal with FBTERM on '
|
|
'the left and Bash on the right. Explicit TTY mode is '
|
|
'vertical with a short FBTERM monitor above Bash. The layout '
|
|
'belongs to the shared tmux window and follows the last '
|
|
'requested view mode; it is not isolated per viewer.',
|
|
'commands': ['fb console', 'fb status console']}]},
|
|
'screens': {'title': 'Authentic screen observation and input',
|
|
'sections': [{'heading': 'Text transcripts and pixels',
|
|
'body': 'A CLI tty transcript describes a terminal and explicitly does '
|
|
'not claim authentic pixels. MCP real-screen CUA-TTY and '
|
|
'graphical screen tools operate through the real screen client '
|
|
'and capture-linked interaction. Use those supported '
|
|
'observation tools when authentic complete screen evidence is '
|
|
'required. Never present a reconstructed terminal, animation or '
|
|
'partial invented view as a real screenshot.',
|
|
'commands': []},
|
|
{'heading': 'Automatic graphical discovery',
|
|
'body': 'The installer and control console stay text interfaces in both '
|
|
'TTY and a desktop terminal. Compatible graphical CUA is '
|
|
'discovered automatically; availability depends on the actual '
|
|
'display/session and permissions. A loaded module is not proof '
|
|
'that real pixel capture or input succeeded. New profiles use '
|
|
'adaptive auto mode: without a verified active X11 session the '
|
|
'runtime provides FBEXEC, FBTERM and CUA-TTY in text mode, '
|
|
'without requiring a graphical login or automatically creating '
|
|
'a private desktop. Explicit virtual-desktop settings remain '
|
|
'advanced options and are labelled separately from '
|
|
'physical-screen evidence.',
|
|
'commands': ['fb status', 'fb doctor']},
|
|
{'heading': 'Frame-buffer read access',
|
|
'body': 'screen-access is a narrow, explicit administrative permission '
|
|
'for reading the real frame buffer. It does not by itself '
|
|
'enable graphical CUA, keyboard/mouse control or arbitrary VT '
|
|
'switching. Persistent read access can remain effective after '
|
|
"logout or a VT switch; review the command's displayed scope "
|
|
'and use normal local administrator authentication.',
|
|
'commands': ['fb screen-access status']},
|
|
{'heading': 'Shared desktop',
|
|
'body': 'A graphical desktop shares focus, keyboard and mouse. Use one '
|
|
'controlling agent per desktop at a time and avoid overlapping '
|
|
'work. This is an operating recommendation, not a claim of '
|
|
'certified automatic isolation. Independent non-overlapping '
|
|
'execution jobs may be possible; do not infer isolation or '
|
|
'physical parallel execution from that alone.',
|
|
'commands': []}]},
|
|
'diagnostics': {'title': 'Status and diagnosis',
|
|
'sections': [{'heading': 'Inspect before acting',
|
|
'body': 'status summarizes current runtime, connection, desired '
|
|
'state and boot policy. A query completing successfully is '
|
|
'distinct from the components being ready. Connection '
|
|
'verification has a freshness boundary; retrying or unknown '
|
|
'must not be treated as connected. Focused status uses the '
|
|
'same underlying state model.',
|
|
'commands': ['fb status',
|
|
'fb status connection',
|
|
'fb status runtime',
|
|
'fb status boot']},
|
|
{'heading': 'Doctor',
|
|
'body': 'doctor diagnoses prerequisites and reports findings with '
|
|
'suggested next steps. It is not an implicit repair, and it '
|
|
'is not a substitute for checking actual live connection '
|
|
'state. Inspect the diagnosis and relevant private '
|
|
'application logs before considering configuration changes.',
|
|
'commands': ['fb doctor']},
|
|
{'heading': 'Logs and progress',
|
|
'body': 'Normal connection presents concise progress and a final '
|
|
'result, then returns to the prompt. Detailed diagnostics '
|
|
'belong in protected application logs. Share only the '
|
|
'minimum relevant redacted result; never expose '
|
|
'credentials, private keys, browser session data or '
|
|
'unrelated personal paths. Avoid rerunning setup, '
|
|
'enrollment or broad lifecycle tests merely because a view '
|
|
'is confusing.',
|
|
'commands': ['fb help connection', 'fb help lifecycle']}]},
|
|
'security': {'title': 'Authorization, distribution and safe operation',
|
|
'sections': [{'heading': 'Authorized scope',
|
|
'body': 'An agent can use the documented CLI and MCP tools within the '
|
|
"user's authorized scope. Reading this guide does not grant "
|
|
'permission. Verify the receiver and selected target. Normal '
|
|
'human terminal/browser authentication remains separate; do '
|
|
'not request credentials in chat or invent phone/Owner-TTY '
|
|
'enrollment requirements. Normal use should operate through '
|
|
'the installed CLI and tools, not edit or rebuild installed '
|
|
'FrameBridge program files. If the owner explicitly requests '
|
|
'development, use a separate source clone, make reviewable '
|
|
'changes, and do not present a modified build as an official '
|
|
'release. This operating guidance does not restrict GNU GPL '
|
|
'freedoms or require private forks to submit changes upstream.',
|
|
'commands': []},
|
|
{'heading': 'Official releases',
|
|
'body': 'The source is distributed under GNU GPLv3-only terms and the '
|
|
'applicable third-party notices. Verify official release '
|
|
'checksums and published signatures/repository metadata before '
|
|
'installing. Signature verification identifies the publisher '
|
|
'and detects alteration; it does not prohibit lawful modified '
|
|
'versions. Official releases are reviewed through the '
|
|
"project's release process.",
|
|
'commands': []},
|
|
{'heading': 'Side effects',
|
|
'body': 'Read status before service stop, credential forgetting, node '
|
|
'approval, startup-hook changes or administrative screen '
|
|
'permission changes. Explain material scope and consequences '
|
|
"and follow the user's authorization. A sensitive operation "
|
|
'must report the actual result, not just that a query '
|
|
'succeeded. Keep real captures complete and distinguish '
|
|
'observations from hypotheses.',
|
|
'commands': []}]},
|
|
'compatibility': {'title': 'Compatibility with earlier commands',
|
|
'sections': [{'heading': 'Preferred spelling',
|
|
'body': 'Use the short canonical interface in new documentation '
|
|
'and automation. fb and framebridge remain equivalent. '
|
|
'Older connect chatgpt, disconnect chatgpt and connection '
|
|
'status spellings are compatibility routes. New status '
|
|
'scopes replace the need to learn an extra connection '
|
|
'noun.',
|
|
'commands': ['fb connect',
|
|
'fb disconnect',
|
|
'fb status connection']},
|
|
{'heading': 'Legacy lifecycle behavior',
|
|
'body': 'Older root start/stop and autostart commands are '
|
|
'retained for compatibility where documented, but their '
|
|
'historical scopes can differ from the canonical service '
|
|
'controls. In particular, legacy autostart disable '
|
|
'removes managed setup and saved encrypted material; it '
|
|
'is not an alias for boot-policy-only disable. Read the '
|
|
"command's help before using a legacy script.",
|
|
'commands': ['fb help lifecycle']},
|
|
{'heading': 'Versioned help',
|
|
'body': 'This guide describes the installed product and guide '
|
|
'schema. Read the matching release notes for any semantic '
|
|
'migration. The CLI help, MCP guide and static web '
|
|
'documentation are generated from the same reviewed guide '
|
|
'data; a cached manual from an earlier build can describe '
|
|
'a different workflow.',
|
|
'commands': ['fb help compatibility']}]}}
|