NVIDIA-NeMo · aleckhoury · Aug 26, 2026 · Aug 25, 2026 · Aug 25, 2026 · Aug 25, 2026
@@ -31,9 +31,9 @@ User-facing skills in `packages/nemo_platform_ext/src/nemo_platform_ext/skills/`
 
 - `nemo-skill-selection`: entry point when the user's intent is broad or unclear.
 - `nemo-setup`: first-time install and platform startup.
-- `nemo-explore`: design conversation that feeds into a spec.
-- `nemo-spec`: writes an agent spec at `agents/<name>-spec/AGENT-SPEC.md` from explore output.
-- `nemo-build-agent`: scaffolds NAT workflow YAML from the spec and deploys.
+- `nemo-explore`: design conversation that feeds into an Ethos. Always confirms purpose, principles, and vision.
+- `nemo-ethos`: writes an agent Ethos at `agents/<name>-ethos/ETHOS.md` from explore output, then shows a gut-check of the agent.
+- `nemo-build-agent`: scaffolds NAT workflow YAML from the Ethos and deploys.
 - `nemo-try-agent`: test a deployed agent or chat with a model.
 - `nemo-status`: read-only health dashboard. Run this before assuming the platform is up.
 - `nemo-teardown`: guided shutdown with confirmation.

@@ -30,9 +30,9 @@ User-facing skills in `packages/nemo_platform_ext/src/nemo_platform_ext/skills/`
 
 - `nemo-skill-selection`: entry point. Use when the user's intent is broad or unclear.
 - `setup`: verifies that NeMo Platform is installed and running. If install is missing, tells the user how to run the CLI install (`make bootstrap` + `nemo setup`). **Install itself is CLI-only.** Do not attempt to install NeMo via skill-driven pip; the workspace dependency graph and credential handling are not reliably automatable inside a sandbox.
-- `nemo-explore`: design conversation that feeds into a spec.
-- `nemo-spec`: writes an agent spec from explore output.
-- `nemo-build-agent`: scaffolds NAT workflow YAML from the spec and deploys.
+- `nemo-explore`: design conversation that feeds into an Ethos. Always confirms purpose, principles, and vision.
+- `nemo-ethos`: writes `agents/<name>-ethos/ETHOS.md` from explore output, then shows a gut-check of the agent.
+- `nemo-build-agent`: scaffolds NAT workflow YAML from the Ethos and deploys.
 - `nemo-try-agent`: test a deployed agent or chat with a model.
 - `nemo-intake`: instrument agents, choose an ingest format, upload/query telemetry, and attach evaluator results.
 - `nemo-experiments-upload`: publish named evaluation runs and scores to the Experiments leaderboard.

@@ -30,9 +30,9 @@ User-facing skills in `packages/nemo_platform_ext/src/nemo_platform_ext/skills/`
 
 - `nemo-skill-selection`: entry point. Use when the user's intent is broad or unclear ("help me with nemo," "I want to try this," "what does this repo do?").
 - `setup`: verifies that NeMo Platform is installed and running. Hands off if it is; tells the user how to run the CLI install (`make bootstrap` + `nemo setup`) if it isn't. **Install is CLI-only.** Do not attempt skill-driven installation; it has been tried and consistently fails on workspace dependency resolution, credential handling, and Python version friction inside a sandbox.
-- `nemo-explore`: design conversation. Use before `nemo-spec` to figure out what the user's agent needs to do.
-- `nemo-spec`: writes an agent spec at `agents/<name>-spec/AGENT-SPEC.md` from the explore output.
-- `nemo-build-agent`: scaffolds NAT workflow YAML from the spec and deploys.
+- `nemo-explore`: design conversation. Use before `nemo-ethos`. Always confirms purpose, principles, and vision.
+- `nemo-ethos`: writes `agents/<name>-ethos/ETHOS.md` from the explore output, then shows a gut-check of the agent.
+- `nemo-build-agent`: scaffolds NAT workflow YAML from the Ethos and deploys.
 - `nemo-try-agent`: test a deployed agent or chat with a model.
 - `nemo-status`: read-only health dashboard. Run this before assuming the platform is up.
 - `nemo-teardown`: guided shutdown with confirmation.

@@ -2,12 +2,15 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
+schema_version: 1
 name: nemo-studio-assistant
 created_timestamp: 2026-07-28T20:09:49Z
+updated_timestamp: 2026-08-24T00:00:00Z
 author: Danielle Ali and Codex
+owner: nemo-platform-studio
 ---
 
-# Agent Spec: nemo-studio-assistant
+# Ethos: nemo-studio-assistant
 
 > This file is the durable contract for the local NeMo Platform assistant.
 > Keep it aligned with the implementation under `agents/nemo-studio-assistant/`.
@@ -19,12 +22,14 @@ author: Danielle Ali and Codex
 
 Help NeMo Platform developers inspect and operate their current workspace through Studio using the NeMo Platform SDK.
 
-## Purpose
+## Purpose & Outcomes
 
-This agent provides a conversational backend for NeMo Studio so developers can build, deploy, and use a Fabric-hosted agent to interact with NeMo Platform. It should make routine discovery and operational tasks faster without requiring users to translate their intent into CLI commands or raw API requests.
+**Mission.** This agent provides a conversational backend for NeMo Studio so developers can build, deploy, and use a Fabric-hosted agent to interact with NeMo Platform. It should make routine discovery and operational tasks faster without requiring users to translate their intent into CLI commands or raw API requests.
 
 The mission is grounded in the current deployment proof of concept and its implementation: answer simple read-only questions immediately, carry out explicit multi-step platform tasks through supported SDK operations, verify consequential results, and request missing context rather than guessing or entering an unbounded reasoning loop.
 
+**Outcome.** Internal developer tooling, so there is no external revenue or customer-facing metric. The result this agent is accountable for is developer time saved on routine platform operations: a developer should get a correct answer to a read-only workspace question, or a verified result for an explicit multi-step task, without dropping to the CLI or hand-writing API requests. Measured against the Studio proof of concept rather than a business target. No numeric target is agreed yet. Owner: the NeMo Platform Studio team.
+
 ## Scope
 
 - Audience: NeMo Platform developers and internal operators using local Studio or a development environment
@@ -40,18 +45,10 @@ The mission is grounded in the current deployment proof of concept and its imple
 | Platform status helper (`check_status`) | Check evaluation, customization, audit, and Data Designer jobs | Same platform access as the SDK client | Read-only | A service may expose different status subresources; report when no supported status method exists |
 | Packaged agent skills | Supply task-specific playbooks when spec-compliant skills are included in the image | No separate credentials | Depends on the selected playbook and SDK action | The agent must log which skills are loaded; an empty or malformed skills directory means no playbooks are available |
 
-## Model
-
-- Mode: cloud
-- Family: NVIDIA Nemotron 3 Super 120B A12B
-
-## Framework
-
-- Resolution: fabric-deepagents
-- Notes: NeMo Fabric using the preinstalled `nvidia.fabric.langchain.deepagents` adapter
-
 ## Harness
 
+- Selection: fabric-deepagents
+- Source framework: NeMo Fabric using the preinstalled `nvidia.fabric.langchain.deepagents` adapter
 - Description: A Fabric-hosted Deep Agent with packaged skills and a stdio MCP server for NeMo SDK and Studio UI operations
 - Agent loop: Fabric's Deep Agents adapter orchestrates model and MCP tool turns
 - Tool dispatch: Harness-native MCP tools resolve NeMo Platform SDK resources and return serialized results or concise errors
@@ -73,6 +70,13 @@ The mission is grounded in the current deployment proof of concept and its imple
 - Attempt reasonable equivalent SDK operations when a method name differs, but bound retries and do not loop over equivalent failures.
 - Report upstream model, SDK, and service failures honestly. Never claim that a mutation or deployment succeeded without verification.
 - Avoid exposing API keys or secret values in prompts, logs, or responses.
+- Reporting an unavailable plugin resource or an invalid SDK path and stopping is correct behavior, not a failure. Do not retry a call that cannot succeed.
+
+## Principles
+
+- **When a request is ambiguous, ask rather than assume.** This agent mutates real platform state, so a wrong guess costs a user more than an extra turn costs them. The narrower the blast radius, the more latitude to proceed without asking.
+- **Never let a report outrun the verification behind it.** Say what was confirmed, what was attempted, and what is unknown, even when the honest answer is less useful than a confident one. A developer who cannot trust the agent's account of platform state will stop using it.
+- **Prefer the user's stated intent over the convenient interpretation.** If a request is achievable through a narrow read-only path and a broad destructive one, take the narrow path and describe the alternative.
 
 ## Success Criteria
 
@@ -83,6 +87,35 @@ The mission is grounded in the current deployment proof of concept and its imple
 - Studio receives incremental, nonduplicated streaming output and reaches a terminal success or error state.
 - The agent never routes through the CLI, leaks managed credentials, or silently reaches a different NeMo Platform environment.
 
+## Trade-offs
+
+Hard gates, never traded for any gain elsewhere:
+
+- Honesty about outcomes. Never report a mutation or deployment as successful without a verified SDK response.
+- API-only operation. No CLI, shell, or subprocess route, at any latency or quality benefit.
+- Credential safety. No API key or secret value in a prompt, log, or response.
+
+After the gates, in priority order:
+
+1. **Correct clarification over speed.** Asking one focused question beats a fast answer built on a guessed workspace or target.
+2. **Bounded work per request.** A prompt-loop or retry storm that keeps Studio busy is worse than an early, honest failure. Prefer a change that tightens iteration and retry limits over one that improves answer quality by spending more calls.
+3. **Answer quality** on the read-only and multi-step paths.
+4. **Cost per session.** Optimize once the first three hold.
+
+Unacceptable regressions, even alongside a headline win:
+
+- Fast-path hit rate on simple read-only requests must not fall. It is the behavior developers notice first.
+- Clarification quality must not regress into guessing. A silent wrong workspace is far more damaging than a question.
+
+## Constraints
+
+- Approved surface: NeMo Platform Python SDK (`nemo_api`) over the packaged MCP server only. No direct third-party API calls, no CLI, no shell, no arbitrary subprocesses.
+- Model access: cloud models through the deployment's configured platform base URL and inference gateway only. Do not add a provider that bypasses it. The deployed model today is `nvidia-nemotron-3-5-lightning-30b-a3b`, recorded in `agent.yaml`.
+- Secrets: managed by the platform. Never inline a credential into config, prompt, or log output.
+- Telemetry: agent-specific telemetry exporters stay disabled until a reviewed pipeline exists. Diagnosis uses container and platform logs.
+- Blast radius: an ambiguous workspace or destructive target requires clarification. Missing context is never permission to pick a target.
+- Requires approval from the owner before shipping: broadening destructive capabilities, changing deployment mode, enabling a telemetry exporter, or adding a tool with write access beyond the current SDK surface.
+
 ## Evaluation Setup
 
 Unit coverage lives in `agents/nemo-studio-assistant/tests/test_nemo_studio_assistant.py`. Run it with:
@@ -95,6 +128,18 @@ The prior NAT evaluation YAML was removed because it depended on NAT's custom wo
 
 Manual Studio validation is documented in `agents/nemo-studio-assistant/tests/smoke_test.md`. Current coverage gaps include fileset listing, missing-workspace clarification, fast-path failure containment, destructive-action ambiguity, iteration limits, retry limits, cancellation, and end-to-end latency thresholds.
 
+## Metric Semantics
+
+| Field or signal | Meaning | How consumers may use it |
+|---|---|---|
+| fast-path hit rate | Share of requests answered by the deterministic single-SDK-call route rather than the full agent loop. Read from application logs, not from a metrics backend. | Supports claims about routing efficiency. Does not measure answer correctness — a fast path can return the wrong list. |
+| per-request model-call count | Model invocations for one user request, including retries. | A high count signals a runaway loop. Not a cost figure on its own; token volume per call varies widely. |
+| tool-error repetition | Count of identical SDK errors within one request. | Repeated identical errors mean the agent is retrying a call that cannot succeed. Distinct errors are normal exploration, not a defect. |
+| total latency | Wall-clock time from Studio request to terminal state. | Includes upstream model time the agent does not control. Do not attribute a latency regression to the agent without separating model time. |
+| health probe traffic | Container liveness and readiness requests. | Operational noise. Never count these as user traffic or as agent invocations. |
+| unit test pass rate | Result of `test_nemo_studio_assistant.py`, which covers config translation, MCP exposure, and mutation approval. | Evidence about wiring and contracts. Not evidence about production answer quality; there is no automated end-to-end eval suite. |
+| absent agent telemetry spans | Agent-specific exporters are deliberately disabled until a reviewed pipeline exists. | Their absence is not a defect and not evidence of a silent failure. Diagnose from container and platform logs instead. |
+
 ## Change Scope
 
 - System prompt: yes
@@ -103,15 +148,25 @@ Manual Studio validation is documented in `agents/nemo-studio-assistant/tests/sm
 - Inference params: yes
 - Model swap (within mode): yes
 - Skills: yes
+- Deployment mode: with-approval
+- Destructive capability surface: with-approval
+- Agent telemetry exporters: with-approval
 - Fine-tuning: no
-- Notes: Preserve API-only operation, managed secrets, and disabled agent telemetry; require human approval before broadening destructive capabilities or changing deployment mode
+- Notes: Preserve API-only operation and managed secrets. The owner named in the front matter signs off on every `with-approval` lever.
+
+## Vision
+
+**Intention.** Become the way a developer operates NeMo Platform conversationally, so that routine platform work no longer requires knowing which SDK surface owns which resource.
 
-## Signals
+**Target use cases.** Both are out of scope today, and both are directions the agent should not architect itself away from.
 
-Prioritize fast-path hit rate, per-request model-call count, tool-error repetition, total latency, upstream decode timeouts, retry count, clarification quality, and verified task completion. Treat repeated identical SDK errors or dozens of model calls for a simple request as runaway behavior. Routine container health probes are operational noise and should not be interpreted as user traffic. Until a dedicated agent telemetry pipeline is added, use container and platform logs for diagnosis.
+- Diagnosing a failed job end to end — reading the job, its logs, and the related entities, then explaining the failure — rather than answering one lookup at a time.
+- Carrying a multi-turn task across a session, so a developer can refine a deployment over several requests without restating the context each time.
 
 ## Open Questions
 
 - Should `default` always be assumed when Studio does not propagate a workspace, or should the agent ask whenever more than one workspace exists?
 - Which mutation categories require an explicit confirmation step even when the target is unambiguous?
 - What maximum model-call count and wall-clock limit should apply to the complex path?
+- Which mutation categories should stay permanently out of scope rather than gated on approval?
+- What numeric developer-time target should `Purpose & Outcomes` carry?
@@ -31,7 +31,7 @@ result can be verified:
 ```bash
 export NMP_BASE_URL=http://127.0.0.1:8080
 nemo agents create --name nemo-studio-assistant \
-  --agent-config agents/nemo-studio-assistant-spec/agent.yaml
+  --agent-config agents/nemo-studio-assistant-ethos/agent.yaml
 nemo agents package \
   --agent agents/nemo-studio-assistant/agent.yaml \
   --pyproject agents/nemo-studio-assistant/pyproject.toml \

@@ -16,7 +16,7 @@
 from nemo_studio_assistant.mcp_server import create_server
 
 AGENT_ROOT = Path(__file__).parents[1]
-SPEC_ROOT = AGENT_ROOT.parent / "nemo-studio-assistant-spec"
+ETHOS_ROOT = AGENT_ROOT.parent / "nemo-studio-assistant-ethos"
 EVAL_DATA_PATH = AGENT_ROOT / "src/nemo_studio_assistant/nemo-studio-assistant-eval-data.json"
 REAL_PREFLIGHT_GUARDRAIL_MODEL = register._preflight_guardrail_model
 SKILL_PATHS = [
@@ -93,7 +93,7 @@ def test_agent_config_translates_to_fabric_deepagents() -> None:
 
 def test_canonical_registration_config_translates_to_same_runtime() -> None:
     source = translate_agent_config(load_agent_config(AGENT_ROOT / "agent.yaml"))
-    registered = translate_agent_config(load_agent_config(SPEC_ROOT / "agent.yaml"))
+    registered = translate_agent_config(load_agent_config(ETHOS_ROOT / "agent.yaml"))
 
     assert registered.harness == source.harness
     assert registered.models == source.models
@@ -111,10 +111,10 @@ def test_every_configured_skill_is_packaged() -> None:
     assert all(skill_file.is_file() for skill_file in skill_files)
     assert all(skill_file.read_text(encoding="utf-8").startswith("---\n") for skill_file in skill_files)
 
-    registered = load_agent_config(SPEC_ROOT / "agent.yaml")
+    registered = load_agent_config(ETHOS_ROOT / "agent.yaml")
     assert registered.skills is not None
     assert registered.skills.paths == SKILL_PATHS
-    assert all((SPEC_ROOT / skill_path / "SKILL.md").is_file() for skill_path in registered.skills.paths)
+    assert all((ETHOS_ROOT / skill_path / "SKILL.md").is_file() for skill_path in registered.skills.paths)
     assert config.environment.workspace == "."
     assert registered.environment.workspace == "."
 
@@ -197,7 +197,7 @@ def test_fabric_absolute_skill_source_is_virtualized_under_workspace() -> None:
 def test_guardrails_skill_is_generic_sdk_workflow_and_copies_match() -> None:
     source = AGENT_ROOT / "src/nemo_studio_assistant/skills/guardrails/SKILL.md"
     packaged = AGENT_ROOT / "skills/guardrails/SKILL.md"
-    registered = SPEC_ROOT / "skills/guardrails/SKILL.md"
+    registered = ETHOS_ROOT / "skills/guardrails/SKILL.md"
     skill_text = source.read_text(encoding="utf-8")
 
     assert packaged.read_text(encoding="utf-8") == skill_text