TenkaCloud Docs
← Home
日本語 English

Problem author manual Stable

Use this manual when you create or maintain the content participants solve: the scenario, deployable environment, verifier, scoring metadata, and hints. You do not need to operate a TenkaCloud tenant or change platform code.

Your goal

A pack is ready to publish only when another person can reproduce all three outcomes:

  1. make pack-validate succeeds from a fresh checkout.
  2. For a supported local runtime, the author rehearses the complete path from start through flag submission.
  3. Someone who did not build the problem can explain the goal and first action from the participant-facing statement alone.

Decision flow from authoring a problem pack to publication

When local execution is unsupported, record Not run instead of inferring a result. Verify in a supported test environment or tell the organizer that the runtime remains unverified. If the independent reader cannot understand the problem, rewrite its situation, goal, first action, and completion condition before changing the environment.

Create and validate a pack

make pack-init ARGS="./my-first-pack"
make pack-validate ARGS="./my-first-pack"

The first pack tutorial follows one minimal pack from scaffold to validation, immutable Git pin, install, activation, and removal.

Preflight JSON through MCP

An MCP 2026-07-28 client can connect to {ALWAYS_ON_CONTROL_PLANE_ORIGIN}/mcp/problem-author without authentication and call validate_pack_manifest or validate_problem_metadata.

Both tools validate only the supplied JSON, purely and deterministically, against the same Problem SDK contract. They do not access a filesystem, network, cloud environment, environment variable, or credential. Equal input produces equal diagnostics. They cannot prove that referenced files exist, a template starts, local mode works, or a flag can be submitted. Always finish with make pack-validate and the real rehearsal before publishing.

Author the participant experience

Every problem should answer these questions before introducing technical detail:

  1. What happened in the scenario?
  2. What observable result must the participant produce?
  3. What is the first safe action?
  4. Where will the participant work: a URL, shell, cloud console, or local app?
  5. What exact evidence becomes the TC{...} flag?
  6. How can the participant reset or stop the environment?

Explain a term at first use if a participant needs it to act. Avoid testing whether they memorized words such as cloud, container, Docker, region, or database unless that concept is the learning objective.

The problem contract

Part Responsibility
tenkacloud-pack.json Pack identity, version, license, problem root, runtimes, dependencies
metadata.json Problem ID, runtime, template, scoring, endpoints, phases, disruptions
Runtime entry Creates the isolated environment the participant actually uses
Verifier or scoring rule Decides whether the submitted evidence is correct
README / statement Scenario, goal, first action, success condition, cleanup
Hints Progressive help without revealing the final answer too early

Use the generated pack manifest and problem metadata references instead of guessing field names.

Rehearse the real interaction

Validation checks the contract and referenced files, but it does not prove that the problem is understandable or solvable.

  1. Start from a clean local or test environment.
  2. Follow only the participant-facing statement.
  3. Start the deployed or local problem environment.
  4. Perform the intended investigation or repair.
  5. Submit the exact flag through the Participant Portal.
  6. Test one wrong flag, reset, stop, and a second start.
  7. Ask someone who did not author the problem to complete the same path.

Do not show that final tester the implementation, verifier, or correct flag. Publish only when they can explain what happened, what must be fixed, where to start, and what proves completion—and then reach the real flag submission.

Local mode is for problems that declare a supported local runtime. It is not a WordPress tutorial or a substitute for the participant onboarding. A WordPress problem, if desired, belongs here as its own local problem with its own learning objective and verifier.

Publish safely

  • Increment the pack version for a new immutable release.
  • Validate before committing.
  • Pin installation to the full 40-character Git commit SHA.
  • Do not put secrets, mutable remote assets, or install-time scripts in a pack.
  • Keep author-only answers out of participant-visible metadata and endpoints.
  • Give organizers a separate rehearsal note for required accounts, region, expected start time, teardown, and costs.

The security and provenance model defines what a pack may contain. Validator messages are listed in validation errors.

If the pack requires a new platform capability rather than problem content, open a platform Issue and switch to the developer manual.