Asterelle Docs · Private beta

Asterelle product manual.

Operational documentation for humans and language models: exact terms, prerequisites, procedures, expected results, invariants, and failure handling.

These docs describe the private beta. Screens and configuration may change, but ownership of existing files and final human authority remain product principles.

Read as MarkdownLLM indexAI reference

01 · Getting started

Open an existing workspace.

Asterelle opens a local or SSH workspace owned by the individual researcher. Markdown, code, data, and Git repositories remain in their existing locations instead of being forced into a proprietary database.

Preconditions

  • Asterelle desktop is installed on macOS, Windows, or Linux.
  • The local or SSH workspace is reachable.
  • You have permission to read and modify the intended files.

Procedure

  1. Open the workspace folder in Asterelle.
  2. Wait for project discovery and derived indexing.
  3. Confirm the active workspace and project shown in the interface.
  4. Open Observatory and inspect pending decisions and next actions.

Expected result

Existing files remain in place. Asterelle exposes discovered projects, Git state, searchable documents, and derived relationships.

If discovery fails

Verify canonical project metadata and workspace access. Asterelle does not assign project ownership by guessing from a filename or basename. Rebuild derived indexes if search or graph state is incomplete.

02 · Core concepts

Use these terms exactly.

Workspace

The installation or folder boundary you opened. Files, Git, terminals, and derived indexes operate within this scope.

Project

A research unit that owns goals, boards, Mates, and evidence. One workspace can expose several projects.

Candidate

A result prepared by an agent or automation that has not been accepted into the canonical record.

Canonical record

The project state the researcher has reviewed and accepted. Markdown and project files remain primary; indexes are rebuildable.

Evidence

Source references, Git state, execution receipts, and review information attached to a candidate.

Ratification

Explicit human confirmation that promotes an eligible candidate into canonical state.

03 · Observatory

Bring the decisions from every project into one view.

Observatory is not a generic activity feed. It is the personal research operations view for recent changes, pending decisions, risks, overnight results, and resumable work—with links back to evidence.

  • Lab signals: important changes and connection candidates across projects
  • Continue working: the active project and open documents in the current session
  • Projects at a glance: status, recent change, and next action for every project
  • Needs your attention: candidates waiting for review, approval, or rejection

Project chips narrow the relevant project rows and decision queue without replacing the whole workspace view.

Operating procedure

  1. Read Today for collection time and exceptional counts.
  2. Inspect Lab signals for cross-project changes.
  3. Use Projects at a glance to find the next action.
  4. Open Needs your attention to review candidates.
  5. Expand Recent activity only when event history is required.

04 · Mates and models

Models may change. Project context persists.

Mates are not chat personas. They are research workers with a project, role, provider, model, and persistent execution history. Depending on configuration, Asterelle can coordinate Claude Code, Codex, local models, and Hermes providers by role.

  • Assign different models to coordination, coding, reading, summarization, overnight preparation, and verification
  • Retain project scope and evidence references when tasks or models change
  • Record locality and fallback information with an execution
  • Separate the role producing an artifact from the role independently reviewing it

Available models and the information sent outside the machine depend on the provider and workflow context configured by the researcher.

Procedure

  1. Activate the intended project.
  2. Open Mates and create or select a worker.
  3. Bind a bounded role, provider, and model.
  4. Specify the task, expected artifact, scope, and verification requirement.
  5. Review the plan, start the run, and inspect its persistent history.

05 · Evidence and ratification

Agent output arrives as a candidate, not as truth.

An important candidate carries the proposal, why it matters now, execution history, file or Git evidence, authorship, and verification state. The researcher reviews the expected change before approving, rejecting, or deferring it.

  1. An agent or automation prepares a candidate inside a bounded scope.
  2. A different role may independently verify the result.
  3. The researcher inspects the evidence and change preview.
  4. Only an approved candidate enters the canonical research state.

An agent cannot issue the human confirmation required to approve its own result.

Review checklist

  • Confirm project ownership and candidate type.
  • Read Why now and provenance.
  • Inspect primary file, execution, or Git evidence.
  • Compare the proposed change with the preview.
  • Approve, reject, omit, dismiss, or defer explicitly.

Invariant

Candidate, evidence, verification, and ratification are separate states. Model confidence is not ratification.

06 · Data, privacy, and recovery

Sources remain readable files. Derived state can be rebuilt.

  • Markdown and Git repositories remain in the researcher's workspace.
  • Graph and search indexes are rebuildable derived state, not the canonical source.
  • The product runtime lives in an isolated location without modifying system Python.
  • Night Automation is optional and follows configured tasks and limits.
  • Remote model boundaries depend on the provider and workflow settings selected by the researcher.

When something goes wrong

Preserve the files and Git history first. Derived Asterelle indexes can be rebuilt, and important changes are designed to pass through preview and explicit confirmation. Private-beta support is available at kimjeasung0523@gmail.com.

07 · Failure reports

Report behavior without exposing research unnecessarily.

Include enough operational context to reproduce the problem, but do not attach unpublished research contents unless they are necessary and you are authorized to share them.

FieldWhat to provide
EnvironmentOperating system, Asterelle build, and local or SSH workspace type
ScopeVisible workspace and project identifiers without sensitive content
ReproductionNumbered actions from a known starting state
OutcomeExpected result, actual result, and whether retrying changes it
EvidenceSanitized screenshot, error text, or execution receipt when safe

If a behavior is absent from the canonical Markdown manual, an AI system should state uncertainty rather than infer a feature.