@botpress/adk-cli 1.19.0-beta.3 → 1.19.0-beta.5

package/{dist/index-DfjXY3Oo-szsanhnt.js → assets/ui-dist/assets/index-a3ZL0_Jr.js}

@@ -1,4 +1,4 @@
-import{r as a,W as R}from"./index-CSTz-oTK.js";function oe(e,t){(t==null||t>e.length)&&(t=e.length);for(var r=0,n=Array(t);r<t;r++)n[r]=e[r];return n}function me(e){if(Array.isArray(e))return e}function be(e,t,r){return(t=Se(t))in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function ye(e,t){var r=e==null?null:typeof Symbol<"u"&&e[Symbol.iterator]||e["@@iterator"];if(r!=null){var n,o,i,c,s=[],f=!0,p=!1;try{if(i=(r=r.call(e)).next,t!==0)for(;!(f=(n=i.call(r)).done)&&(s.push(n.value),s.length!==t);f=!0);}catch(j){p=!0,o=j}finally{try{if(!f&&r.return!=null&&(c=r.return(),Object(c)!==c))return}finally{if(p)throw o}}return s}}function we(){throw new TypeError(`Invalid attempt to destructure non-iterable instance.
+import{r as a,W as R}from"./index-B3b7PPgV.js";function oe(e,t){(t==null||t>e.length)&&(t=e.length);for(var r=0,n=Array(t);r<t;r++)n[r]=e[r];return n}function me(e){if(Array.isArray(e))return e}function be(e,t,r){return(t=Se(t))in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function ye(e,t){var r=e==null?null:typeof Symbol<"u"&&e[Symbol.iterator]||e["@@iterator"];if(r!=null){var n,o,i,c,s=[],f=!0,p=!1;try{if(i=(r=r.call(e)).next,t!==0)for(;!(f=(n=i.call(r)).done)&&(s.push(n.value),s.length!==t);f=!0);}catch(j){p=!0,o=j}finally{try{if(!f&&r.return!=null&&(c=r.return(),Object(c)!==c))return}finally{if(p)throw o}}return s}}function we(){throw new TypeError(`Invalid attempt to destructure non-iterable instance.
 In order to be iterable, non-array objects must have a [Symbol.iterator]() method.`)}function ie(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter(function(o){return Object.getOwnPropertyDescriptor(e,o).enumerable})),r.push.apply(r,n)}return r}function ae(e){for(var t=1;t<arguments.length;t++){var r=arguments[t]!=null?arguments[t]:{};t%2?ie(Object(r),!0).forEach(function(n){be(e,n,r[n])}):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(r)):ie(Object(r)).forEach(function(n){Object.defineProperty(e,n,Object.getOwnPropertyDescriptor(r,n))})}return e}function Oe(e,t){if(e==null)return{};var r,n,o=je(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n<i.length;n++)r=i[n],t.indexOf(r)===-1&&{}.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}function je(e,t){if(e==null)return{};var r={};for(var n in e)if({}.hasOwnProperty.call(e,n)){if(t.indexOf(n)!==-1)continue;r[n]=e[n]}return r}function Me(e,t){return me(e)||ye(e,t)||Ee(e,t)||we()}function Pe(e,t){if(typeof e!="object"||!e)return e;var r=e[Symbol.toPrimitive];if(r!==void 0){var n=r.call(e,t);if(typeof n!="object")return n;throw new TypeError("@@toPrimitive must return a primitive value.")}return(t==="string"?String:Number)(e)}function Se(e){var t=Pe(e,"string");return typeof t=="symbol"?t:t+""}function Ee(e,t){if(e){if(typeof e=="string")return oe(e,t);var r={}.toString.call(e).slice(8,-1);return r==="Object"&&e.constructor&&(r=e.constructor.name),r==="Map"||r==="Set"?Array.from(e):r==="Arguments"||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(r)?oe(e,t):void 0}}function Re(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function ue(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter(function(o){return Object.getOwnPropertyDescriptor(e,o).enumerable})),r.push.apply(r,n)}return r}function ce(e){for(var t=1;t<arguments.length;t++){var r=arguments[t]!=null?arguments[t]:{};t%2?ue(Object(r),!0).forEach(function(n){Re(e,n,r[n])}):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(r)):ue(Object(r)).forEach(function(n){Object.defineProperty(e,n,Object.getOwnPropertyDescriptor(r,n))})}return e}function Ie(){for(var e=arguments.length,t=new Array(e),r=0;r<e;r++)t[r]=arguments[r];return function(n){return t.reduceRight(function(o,i){return i(o)},n)}}function A(e){return function t(){for(var r=this,n=arguments.length,o=new Array(n),i=0;i<n;i++)o[i]=arguments[i];return o.length>=e.length?e.apply(this,o):function(){for(var c=arguments.length,s=new Array(c),f=0;f<c;f++)s[f]=arguments[f];return t.apply(r,[].concat(o,s))}}}function U(e){return{}.toString.call(e).includes("Object")}function Te(e){return!Object.keys(e).length}function D(e){return typeof e=="function"}function Ce(e,t){return Object.prototype.hasOwnProperty.call(e,t)}function Le(e,t){return U(t)||P("changeType"),Object.keys(t).some(function(r){return!Ce(e,r)})&&P("changeField"),t}function Ae(e){D(e)||P("selectorType")}function $e(e){D(e)||U(e)||P("handlerType"),U(e)&&Object.values(e).some(function(t){return!D(t)})&&P("handlersType")}function De(e){e||P("initialIsRequired"),U(e)||P("initialType"),Te(e)&&P("initialContent")}function Ve(e,t){throw new Error(e[t]||e.default)}var xe={initialIsRequired:"initial state is required",initialType:"initial state should be an object",initialContent:"initial state shouldn't be an empty object",handlerType:"handler should be an object or a function",handlersType:"all handlers should be a functions",selectorType:"selector should be a function",changeType:"provided value of changes should be an object",changeField:'it seams you want to change a field in the state which is not specified in the "initial" state',default:"an unknown error accured in `state-local` package"},P=A(Ve)(xe),q={changes:Le,selector:Ae,handler:$e,initial:De};function Ne(e){var t=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{};q.initial(e),q.handler(t);var r={current:e},n=A(Ue)(r,t),o=A(ze)(r),i=A(q.changes)(e),c=A(qe)(r);function s(){var p=arguments.length>0&&arguments[0]!==void 0?arguments[0]:function(j){return j};return q.selector(p),p(r.current)}function f(p){Ie(n,o,i,c)(p)}return[s,f]}function qe(e,t){return D(t)?t(e.current):t}function ze(e,t){return e.current=ce(ce({},e.current),t),t}function Ue(e,t,r){return D(t)?t(e.current):Object.keys(r).forEach(function(n){var o;return(o=t[n])===null||o===void 0?void 0:o.call(t,e.current[n])}),r}var Fe={create:Ne},We={paths:{vs:"https://cdn.jsdelivr.net/npm/monaco-editor@0.55.1/min/vs"}};function He(e){return function t(){for(var r=this,n=arguments.length,o=new Array(n),i=0;i<n;i++)o[i]=arguments[i];return o.length>=e.length?e.apply(this,o):function(){for(var c=arguments.length,s=new Array(c),f=0;f<c;f++)s[f]=arguments[f];return t.apply(r,[].concat(o,s))}}}function _e(e){return{}.toString.call(e).includes("Object")}function Be(e){return e||le("configIsRequired"),_e(e)||le("configType"),e.urls?(Ke(),{paths:{vs:e.urls.monacoBase}}):e}function Ke(){console.warn(se.deprecation)}function Ge(e,t){throw new Error(e[t]||e.default)}var se={configIsRequired:"the configuration object is required",configType:"the configuration object should be an object",default:"an unknown error accured in `@monaco-editor/loader` package",deprecation:`Deprecation warning!
     You are using deprecated way of configuration.
 
@@ -9,4 +9,4 @@ In order to be iterable, non-array objects must have a [Symbol.iterator]() metho
 
     For more please check the link https://github.com/suren-atoyan/monaco-loader#config
   `},le=He(Ge)(se),Ye={config:Be},Je=function(){for(var t=arguments.length,r=new Array(t),n=0;n<t;n++)r[n]=arguments[n];return function(o){return r.reduceRight(function(i,c){return c(i)},o)}};function fe(e,t){return Object.keys(t).forEach(function(r){t[r]instanceof Object&&e[r]&&Object.assign(t[r],fe(e[r],t[r]))}),ae(ae({},e),t)}var Qe={type:"cancelation",msg:"operation is manually canceled"};function Z(e){var t=!1,r=new Promise(function(n,o){e.then(function(i){return t?o(Qe):n(i)}),e.catch(o)});return r.cancel=function(){return t=!0},r}var Xe=["monaco"],Ze=Fe.create({config:We,isInitialized:!1,resolve:null,reject:null,monaco:null}),de=Me(Ze,2),V=de[0],W=de[1];function ke(e){var t=Ye.config(e),r=t.monaco,n=Oe(t,Xe);W(function(o){return{config:fe(o.config,n),monaco:r}})}function et(){var e=V(function(t){var r=t.monaco,n=t.isInitialized,o=t.resolve;return{monaco:r,isInitialized:n,resolve:o}});if(!e.isInitialized){if(W({isInitialized:!0}),e.monaco)return e.resolve(e.monaco),Z(k);if(window.monaco&&window.monaco.editor)return pe(window.monaco),e.resolve(window.monaco),Z(k);Je(tt,nt)(ot)}return Z(k)}function tt(e){return document.body.appendChild(e)}function rt(e){var t=document.createElement("script");return e&&(t.src=e),t}function nt(e){var t=V(function(n){var o=n.config,i=n.reject;return{config:o,reject:i}}),r=rt("".concat(t.config.paths.vs,"/loader.js"));return r.onload=function(){return e()},r.onerror=t.reject,r}function ot(){var e=V(function(r){var n=r.config,o=r.resolve,i=r.reject;return{config:n,resolve:o,reject:i}}),t=window.require;t.config(e.config),t(["vs/editor/editor.main"],function(r){var n=r.m||r;pe(n),e.resolve(n)},function(r){e.reject(r)})}function pe(e){V().monaco||W({monaco:e})}function it(){return V(function(e){var t=e.monaco;return t})}var k=new Promise(function(e,t){return W({resolve:e,reject:t})}),F={config:ke,init:et,__getMonacoInstance:it},at={wrapper:{display:"flex",position:"relative",textAlign:"initial"},fullWidth:{width:"100%"},hide:{display:"none"}},ee=at,ut={container:{display:"flex",height:"100%",width:"100%",justifyContent:"center",alignItems:"center"}},ct=ut;function lt({children:e}){return R.createElement("div",{style:ct.container},e)}var st=lt,ft=st;function dt({width:e,height:t,isEditorReady:r,loading:n,_ref:o,className:i,wrapperProps:c}){return R.createElement("section",{style:{...ee.wrapper,width:e,height:t},...c},!r&&R.createElement(ft,null,n),R.createElement("div",{ref:o,style:{...ee.fullWidth,...!r&&ee.hide},className:i}))}var pt=dt,ge=a.memo(pt);function gt(e){a.useEffect(e,[])}var te=gt;function ht(e,t,r=!0){let n=a.useRef(!0);a.useEffect(n.current||!r?()=>{n.current=!1}:e,t)}var w=ht;function $(){}function E(e,t,r,n){return vt(e,n)||mt(e,t,r,n)}function vt(e,t){return e.editor.getModel(he(e,t))}function mt(e,t,r,n){return e.editor.createModel(t,r,n?he(e,n):void 0)}function he(e,t){return e.Uri.parse(t)}function bt({original:e,modified:t,language:r,originalLanguage:n,modifiedLanguage:o,originalModelPath:i,modifiedModelPath:c,keepCurrentOriginalModel:s=!1,keepCurrentModifiedModel:f=!1,theme:p="light",loading:j="Loading...",options:O={},height:H="100%",width:_="100%",className:B,wrapperProps:K={},beforeMount:G=$,onMount:Y=$}){let[y,I]=a.useState(!1),[T,g]=a.useState(!0),h=a.useRef(null),d=a.useRef(null),C=a.useRef(null),m=a.useRef(Y),u=a.useRef(G),S=a.useRef(!1);te(()=>{let l=F.init();return l.then(v=>(d.current=v)&&g(!1)).catch(v=>v?.type!=="cancelation"&&console.error("Monaco initialization: error:",v)),()=>h.current?L():l.cancel()}),w(()=>{if(h.current&&d.current){let l=h.current.getOriginalEditor(),v=E(d.current,e||"",n||r||"text",i||"");v!==l.getModel()&&l.setModel(v)}},[i],y),w(()=>{if(h.current&&d.current){let l=h.current.getModifiedEditor(),v=E(d.current,t||"",o||r||"text",c||"");v!==l.getModel()&&l.setModel(v)}},[c],y),w(()=>{let l=h.current.getModifiedEditor();l.getOption(d.current.editor.EditorOption.readOnly)?l.setValue(t||""):t!==l.getValue()&&(l.executeEdits("",[{range:l.getModel().getFullModelRange(),text:t||"",forceMoveMarkers:!0}]),l.pushUndoStop())},[t],y),w(()=>{h.current?.getModel()?.original.setValue(e||"")},[e],y),w(()=>{let{original:l,modified:v}=h.current.getModel();d.current.editor.setModelLanguage(l,n||r||"text"),d.current.editor.setModelLanguage(v,o||r||"text")},[r,n,o],y),w(()=>{d.current?.editor.setTheme(p)},[p],y),w(()=>{h.current?.updateOptions(O)},[O],y);let x=a.useCallback(()=>{if(!d.current)return;u.current(d.current);let l=E(d.current,e||"",n||r||"text",i||""),v=E(d.current,t||"",o||r||"text",c||"");h.current?.setModel({original:l,modified:v})},[r,t,o,e,n,i,c]),N=a.useCallback(()=>{!S.current&&C.current&&(h.current=d.current.editor.createDiffEditor(C.current,{automaticLayout:!0,...O}),x(),d.current?.editor.setTheme(p),I(!0),S.current=!0)},[O,p,x]);a.useEffect(()=>{y&&m.current(h.current,d.current)},[y]),a.useEffect(()=>{!T&&!y&&N()},[T,y,N]);function L(){let l=h.current?.getModel();s||l?.original?.dispose(),f||l?.modified?.dispose(),h.current?.dispose()}return R.createElement(ge,{width:_,height:H,isEditorReady:y,loading:j,_ref:C,className:B,wrapperProps:K})}var yt=bt,Rt=a.memo(yt);function wt(){let[e,t]=a.useState(F.__getMonacoInstance());return te(()=>{let r;return e||(r=F.init(),r.then(n=>{t(n)})),()=>r?.cancel()}),e}var It=wt;function Ot(e){let t=a.useRef();return a.useEffect(()=>{t.current=e},[e]),t.current}var jt=Ot,z=new Map;function Mt({defaultValue:e,defaultLanguage:t,defaultPath:r,value:n,language:o,path:i,theme:c="light",line:s,loading:f="Loading...",options:p={},overrideServices:j={},saveViewState:O=!0,keepCurrentModel:H=!1,width:_="100%",height:B="100%",className:K,wrapperProps:G={},beforeMount:Y=$,onMount:y=$,onChange:I,onValidate:T=$}){let[g,h]=a.useState(!1),[d,C]=a.useState(!0),m=a.useRef(null),u=a.useRef(null),S=a.useRef(null),x=a.useRef(y),N=a.useRef(Y),L=a.useRef(),l=a.useRef(n),v=jt(i),re=a.useRef(!1),J=a.useRef(!1);te(()=>{let b=F.init();return b.then(M=>(m.current=M)&&C(!1)).catch(M=>M?.type!=="cancelation"&&console.error("Monaco initialization: error:",M)),()=>u.current?ve():b.cancel()}),w(()=>{let b=E(m.current,e||n||"",t||o||"",i||r||"");b!==u.current?.getModel()&&(O&&z.set(v,u.current?.saveViewState()),u.current?.setModel(b),O&&u.current?.restoreViewState(z.get(i)))},[i],g),w(()=>{u.current?.updateOptions(p)},[p],g),w(()=>{!u.current||n===void 0||(u.current.getOption(m.current.editor.EditorOption.readOnly)?u.current.setValue(n):n!==u.current.getValue()&&(J.current=!0,u.current.executeEdits("",[{range:u.current.getModel().getFullModelRange(),text:n,forceMoveMarkers:!0}]),u.current.pushUndoStop(),J.current=!1))},[n],g),w(()=>{let b=u.current?.getModel();b&&o&&m.current?.editor.setModelLanguage(b,o)},[o],g),w(()=>{s!==void 0&&u.current?.revealLine(s)},[s],g),w(()=>{m.current?.editor.setTheme(c)},[c],g);let ne=a.useCallback(()=>{if(!(!S.current||!m.current)&&!re.current){N.current(m.current);let b=i||r,M=E(m.current,n||e||"",t||o||"",b||"");u.current=m.current?.editor.create(S.current,{model:M,automaticLayout:!0,...p},j),O&&u.current.restoreViewState(z.get(b)),m.current.editor.setTheme(c),s!==void 0&&u.current.revealLine(s),h(!0),re.current=!0}},[e,t,r,n,o,i,p,j,O,c,s]);a.useEffect(()=>{g&&x.current(u.current,m.current)},[g]),a.useEffect(()=>{!d&&!g&&ne()},[d,g,ne]),l.current=n,a.useEffect(()=>{g&&I&&(L.current?.dispose(),L.current=u.current?.onDidChangeModelContent(b=>{J.current||I(u.current.getValue(),b)}))},[g,I]),a.useEffect(()=>{if(g){let b=m.current.editor.onDidChangeMarkers(M=>{let Q=u.current.getModel()?.uri;if(Q&&M.find(X=>X.path===Q.path)){let X=m.current.editor.getModelMarkers({resource:Q});T?.(X)}});return()=>{b?.dispose()}}return()=>{}},[g,T]);function ve(){L.current?.dispose(),H?O&&z.set(i,u.current.saveViewState()):u.current.getModel()?.dispose(),u.current.dispose()}return R.createElement(ge,{width:_,height:B,isEditorReady:g,loading:f,_ref:S,className:K,wrapperProps:G})}var Pt=Mt,St=a.memo(Pt),Tt=St;export{Rt as DiffEditor,St as Editor,Tt as default,F as loader,It as useMonaco};
-//# sourceMappingURL=index-DfjXY3Oo.js.map
+//# sourceMappingURL=index-a3ZL0_Jr.js.map

package/assets/ui-dist/index.html

@@ -15,8 +15,8 @@
         }
       }
     </script>
-    <script type="module" crossorigin src="/assets/index-CSTz-oTK.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-DAztRXeA.css">
+    <script type="module" crossorigin src="/assets/index-B3b7PPgV.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DIFGtVmI.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/{README-wjb7z7f0.md → README-824wa4jj.md}

@@ -32,7 +32,7 @@ flowchart TD
     C --> E[copyDirRecursive]
     D --> E
     E --> F["Replace {{projectName}}, {{runtimeVersion}}, {{packageManager}}"]
-    F --> G[Write CLAUDE.md + agent.json if missing]
+    F --> G[Write CLAUDE.md, AGENTS.md + agent.json if missing]
     G --> H["Install dependencies (integrations, plugins)"]
 ```
 

package/dist/SKILL-75ym6tcj.md

@@ -0,0 +1,257 @@
+---
+name: adk-debugger
+description: Systematic debugging for ADK agents — trace reading, log analysis, common failure diagnosis, and the debug loop.
+license: MIT
+---
+
+# ADK Debugger Skill
+
+## What is ADK Debugging?
+
+Every ADK agent records its behavior as traces and logs — every conversation turn, tool call, LLM reasoning step, and error. These are the source of truth for understanding what your agent did and why.
+
+The ADK CLI provides the tools you need to debug. Most diagnostic commands support `--format json`; use it for programmatic output. The exception is `adk dev`, which has no `--format` flag and uses `adk dev --non-interactive` for structured NDJSON output.
+
+## When to Use This Skill
+
+Use this skill when the developer asks about:
+
+- **Bot not working** — not responding, wrong responses, unexpected behavior
+- **Tool issues** — wrong tool called, tool errors, hallucinated parameters
+- **Workflow problems** — stuck workflows, steps not executing, state issues
+- **Reading traces/logs** — how to query, filter, and interpret debug output
+- **LLM misbehavior** — hallucinations, refusals, looping, poor extraction
+- **Build/deploy failures** — validation errors, schema mismatches
+- **Config issues** — agent.json vs agent.local.json, integration setup
+- **Post-fix verification** — confirming a fix worked, writing regression evals
+
+**Trigger questions:**
+- "My bot isn't responding"
+- "The wrong tool was called"
+- "My workflow is stuck"
+- "How do I read traces?"
+- "How do I check logs?"
+- "The LLM is hallucinating"
+- "Something broke after my last change"
+- "My deploy failed"
+- "`adk check` found errors"
+- "Summarize this trace"
+- "What happened in trace X?"
+- "Give me an overview of this conversation turn"
+- "Why did the bot do X in this trace?"
+- "Walk me through what happened"
+- "How do I debug this?"
+- "Summarize this conversation"
+- "Explain what happened in conversation X"
+- "Why did the bot respond that way?"
+- "Walk me through this conversation"
+- "What went wrong in this conversation?"
+
+## Available Documentation
+
+| File | Contents |
+|------|----------|
+| `references/traces-and-logs.md` | CLI debugging tools, log querying, trace structure, span types, `onTrace` hooks, reproduction with `adk chat` |
+| `references/common-failures.md` | Runtime failure patterns — validation, bot not responding, tool errors, workflow stuck, integration failures, build errors, config confusion |
+| `references/llm-debugging.md` | LLM behavior issues — wrong tool, hallucinated params, refusals, token limits, looping, reading model reasoning |
+| `references/debug-workflow.md` | The systematic 8-step debug loop: validate → reproduce → logs → traces → classify → fix → verify → prevent |
+| `references/trace-summarization.md` | How to fetch, walk, and summarize traces as free-form natural-language narratives — adapting depth to context |
+| `references/conversation-analysis.md` | How to summarize and explain full conversations — listing conversations, timeline analysis, correlating with traces, common patterns |
+
+## How to Answer
+
+1. **"How do I read traces/logs?"** → Read `traces-and-logs.md` for CLI commands and trace structure
+2. **Something is broken, known pattern** → Read `common-failures.md` for the matching failure pattern
+3. **LLM is misbehaving** → Read `llm-debugging.md` for the matching behavior issue
+4. **Systematic investigation needed** → Read `debug-workflow.md` and follow the 8-step loop
+5. **"Summarize this trace" / "What happened?"** → Read `trace-summarization.md` for how to fetch, walk, and narrate traces
+6. **"Summarize this conversation" / "Explain what happened"** → Read `conversation-analysis.md` for multi-turn conversation summaries and explanations
+7. **After fixing, need to prevent regression** → Point to the `adk-evals` skill for writing evals
+
+---
+
+## Quick Reference
+
+### The Debug Loop
+
+```
+symptom → validate (adk check) → reproduce (adk chat) → logs (adk logs) → traces (adk traces) → root cause → fix → verify
+```
+
+### CLI Commands (prefer structured output)
+
+```bash
+adk check --format json                         # offline validation
+adk logs error --format json                     # recent errors
+adk logs --follow --format json                  # stream live
+adk traces --format json                         # recent traces
+adk traces conversation=<id> --format json       # specific conversation
+adk chat --single "msg" --format json            # test message
+adk dev --non-interactive                        # structured NDJSON dev output (no TUI)
+adk conversations --format json                  # list recent conversations
+adk conversations show <id> --format json        # conversation timeline
+adk conversations show <id> --include-llm --format json  # timeline with LLM reasoning
+```
+
+### Span Types
+
+| Type | What It Shows |
+|------|--------------|
+| `think` | LLM reasoning — why it chose an action |
+| `tool_call` | Tool invocation — name, input, output, success/error |
+| `code_execution_exception` | Runtime error — message and stack trace |
+| `end` | Conversation turn completed |
+
+---
+
+## Prerequisites Check
+
+Before debugging, verify:
+
+- [ ] **Project valid?** Run `adk check --format json` — fix any reported issues first
+- [ ] **Dev server running?** `adk dev` (or `adk dev --non-interactive` for structured NDJSON output)
+- [ ] **Bot linked?** `agent.json` exists with `botId` and `workspaceId` (created by `adk link`)
+- [ ] **Dev bot created?** `agent.local.json` has `devId` (set automatically by the first `adk dev` run)
+- [ ] **Integration configured?** Check Dev Console at localhost:3001 for unconfigured integrations
+
+---
+
+## Critical Patterns
+
+✅ **Run `adk check` before debugging runtime issues**
+
+```bash
+# CORRECT — catch config/schema problems offline first
+adk check --format json
+# Then debug runtime issues
+```
+
+❌ **Skipping offline validation**
+
+```bash
+# WRONG — jumping straight to runtime debugging wastes time on config issues
+adk traces --format json  # might be chasing a config problem
+```
+
+---
+
+✅ **Use `--format json` on all CLI commands**
+
+```bash
+# CORRECT — structured output for reliable parsing
+adk logs error --format json
+adk traces --format json
+adk chat --single "test" --format json
+```
+
+❌ **Parsing human-readable output**
+
+```bash
+# WRONG — human-readable format is for display, not parsing
+adk logs error
+adk traces
+```
+
+---
+
+✅ **Use `adk logs error` to filter errors**
+
+```bash
+# CORRECT — focused error scan
+adk logs error --format json
+adk logs warning since=1h --format json
+```
+
+❌ **Scrolling through all output**
+
+```bash
+# WRONG — too much noise, easy to miss the actual error
+adk logs --format json  # 50 entries of everything
+```
+
+---
+
+✅ **Use `onTrace` hooks for programmatic monitoring**
+
+```typescript
+// CORRECT — structured, automated trace analysis
+hooks: {
+  onTrace: ({ trace }) => {
+    if (trace.type === "tool_call" && !trace.success) {
+      console.error(`[TOOL ERROR] ${trace.tool_name}`, trace.error);
+    }
+  }
+}
+```
+
+❌ **Only checking console output**
+
+```typescript
+// WRONG — console.log in handlers misses the structured trace data
+handler: async (input) => {
+  console.log("tool called");  // not useful for debugging
+}
+```
+
+---
+
+✅ **Write a regression eval after fixing**
+
+```typescript
+// CORRECT — prevents the bug from coming back
+export default new Eval({
+  name: 'fix-order-lookup',
+  type: 'regression',
+  conversation: [{ user: 'Look up order 123', assert: { tools: [{ called: 'lookupOrder' }] } }],
+})
+```
+
+❌ **Fixing and moving on**
+
+```
+// WRONG — the same bug will return and you'll debug it again
+```
+
+---
+
+## Example Questions
+
+**Basic:**
+- "My bot isn't responding — how do I figure out why?"
+- "How do I check for errors in my ADK project?"
+- "What's the difference between agent.json and agent.local.json?"
+
+**Intermediate:**
+- "The bot called createTicket instead of lookupTicket — how do I fix this?"
+- "My workflow starts but the second step never runs"
+- "How do I see what the LLM was thinking when it made a decision?"
+- "Integration actions are failing with auth errors"
+
+**Advanced:**
+- "How do I set up onTrace hooks for automated error detection?"
+- "The model loops on the same tool call — how do I add a guardrail?"
+- "How do I monitor tool call performance with timing metrics?"
+- "How do I systematically debug a multi-step workflow failure?"
+
+---
+
+## Response Format
+
+**Match depth to the question.**
+
+### Simple questions ("how do I check logs?", "what are trace spans?")
+
+Answer directly — one sentence + the CLI command or concept. Don't run the full debug loop for informational questions.
+
+### Active debugging ("my bot is broken", "X isn't working")
+
+Follow the full loop:
+
+1. **Check prerequisites** — verify dev server, config files, project validation
+2. **Start with `adk check --format json`** — rule out offline issues
+3. **Reproduce** — use `adk chat --single "msg" --format json` to create a clean reproduction
+4. **Read the evidence** — `adk logs error --format json` for quick scan, `adk traces --format json` for details
+5. **Identify the root cause** — point to the specific span, log entry, or config issue
+6. **Suggest a targeted fix** — reference the appropriate failure pattern doc
+7. **Verify** — re-run the reproduction, confirm clean output
+8. **Write a regression eval** — load the `adk-evals` skill and generate the eval file automatically