SCNet HPC

SkillHub distribution: bundled profiles use .conf.txt; VERSION.txt records the release.
Loaders support these files and user-created .conf profiles without restoring or renaming files.

Use OpenAPI AK/SK as the preferred backend for structured cluster operations. Keep SSH as the
secondary backend for environment setup, compilation, interactive diagnosis, and operations not
available through the API. Never silently switch backends.

First use and selection

• On first use or missing credentials, read references/first-use.md and explain in the user's
  language what is needed, where to obtain it, and the next local command before starting setup.
  Prefer OpenAPI (platform username + AK/SK); request SSH credentials only for SSH operations.
  Explain-only/offline work needs no credentials. Reuse working configuration without re-entry.
• Never request AK/SK or private-key contents in chat. Give a command using the resolved absolute
  Skill path so users can enter secrets in their own terminal; do not launch hidden prompts in
  an agent tool session. Read references/openapi.md or references/setup.md for backend details.
• Run scripts/setup.sh new|modify|status|reset for explicit configuration lifecycle.
  OpenAPI setup requires Python 3. With no saved preference, default to OpenAPI; credentials
  can come from environment variables or the supported OS credential store.
• Advanced OpenAPI discovery: python3 scripts/scnet.py setup.
• Read-only preflight: python3 scripts/scnet.py doctor.
• Backend precedence: --backend, SCNET_HPC_BACKEND, saved setup choice, profile
  DEFAULT_BACKEND, then openapi.
• Read bundled clusters/<cluster>.conf.txt (or local .conf) before reporting static facts. Treat
  clusters/.cache/<cluster>.auto.conf as optional, time-sensitive SSH probe data.
• With multiple profiles, require an explicit cluster before access changes, installation,
  job generation, or submission. Query the selected backend for live queues, limits, and state.
• SSH setup is profile-scoped; record usernames and key expiry metadata per profile. OpenAPI
  credentials are platform-scoped and discover all authorized regions/schedulers automatically.
• OpenAPI may enable multiple regions locally, but every mutating operation must resolve to one
  explicit/default target region.

Read references/backends.md for backend selection and extension.
Read references/openapi.md for OpenAPI credentials and limits.

Route only as needed

• SSH access: references/setup.md
• Python/modules/offline dependencies: references/environment.md
• Scheduler/runtime/accelerator diagnosis: references/troubleshooting.md
• Add or refresh profiles: references/adding-cluster.md
• Hygon DCU/DTK/HIP/profiling: references/hygon-dcu-development.md
• Compatibility reports: references/software-compatibility.md
• English instructions: references/quickstart-en.md

Read only the selected profile and references needed for the current operation. Profile values
override examples.

Boundaries and evidence

• Read-only inspection and local generation do not authorize remote mutation.
• Resolve backend, target, paths, command, and expected effect before submit, cancel, upload,
  download, overwrite, deletion, or SSH configuration. Never silently retry submission.
• Compute probes consume scheduler resources; run them only when requested or required for
  target-node evidence.
• Keep credentials, tokens, personal paths, internal hosts, nodes, job IDs, and private mirrors
  out of profiles and public reports.
• Preserve existing SSH configuration; use scripts/setup-ssh.sh for bounded changes.
• Respect profile-specific partition, GRES, memory, walltime, offline-network, and shared-storage
  constraints. Propagate workload exit status.
• Distinguish profile values, live scheduler state, login-node evidence, compute-node evidence,
  and inference. Treat Hygon guidance as architecture/toolchain-specific.

Stable entrypoints

• scripts/setup.sh: first-use configuration panel.
• python3 scripts/scnet.py ...: backend-neutral operations, dry-run, raw output, and doctor.
• python3 scripts/scnet.py notebook ...: Notebook discovery and confirmation-driven
  lifecycle operations. Use --dry-run before create/start/stop/release.
• scripts/new-job.sh: profile-aware Slurm generation.
• scripts/refresh-cluster.sh: SSH-derived profile refresh.
• scripts/probe-cluster.sh: initial profile creation.
• scripts/run-compute-probe.sh: bounded accelerator probe.

Use compact normalized output by default. Use --details for full normalized fields and
--raw only for diagnosis. Prefer bounded wait over sending every polling response to the
model. FINALIZING means the OpenAPI accounting state is not yet confirmed.