doc updates

Author: sfc-gh-clakkad

README.adoc

@@ -4,8 +4,8 @@
 
 *Author*: Chinmayee Lakkad
 *Email*: link:mailto:chinmayee.lakkad@snowflake.com[chinmayee.lakkad@snowflake.com]
-*Release Date*: November 2025
-*Version*: 2.0.0
+*Release Date*: March 2026
+*Version*: 2.1.0
 
 toc::[]
 

ascii-docs/DEMOS.adoc

@@ -51,8 +51,8 @@ Both data engineering scenarios can be run together as well as separately.
 ** Document metadata lands in `DOCUMENTS` directory table and its associated stream table
 
 . *Processing*: Document models are refreshed through the triggered task:
-** Document models are refreshed through the triggered task:
-*** incm_root_triggered_docs_processing
++
+*** `incm_root_triggered_docs_processing`
 ** Models use AI to extract text from the documents (PDFs, Word documents, etc.) uploaded to Snowflake.
 ** Models use AI to extract questions and answers from the documents.
 ** Models create a view for processing in Gold Zone.

ascii-docs/SETUP.adoc

@@ -78,9 +78,17 @@ If you change any of the below parameters, be sure to change the `profiles.yml`
 ** `DBT_PROJECT_ADMIN_ROLE={default-role}`
 ====
 +
-Edit the `{env-file}` file and configure all variables except this one (generated later):
+Edit the `{env-file}` file and configure *required* variables:
 +
-** `DBT_SNOWFLAKE_PASSWORD`
+** `GIT_REPOSITORY_URL` — your forked repository URL
+** `GIT_USER_EMAIL` — your Git email
+** `GIT_USER_REPO_PAT` — a GitHub personal access token
+** `DBT_DEPS_EAI` — external access integration object
+** `SNOWFLAKE_INTELLIGENCE_INT_OBJECT` — Snowflake Intelligence integration object
+** `CORTEX_SEARCH_WH` — warehouse for the Cortex Search service
+** `CORTEX_SEARCH_SERVICE_NAME` — name for the Cortex Search service
++
+Leave `DBT_SNOWFLAKE_PASSWORD` empty (generated later).
 
 
 . Setup Snowflake Infrastructure
@@ -101,8 +109,11 @@ Role setup commands require ACCOUNTADMIN privileges
 +
 [source,bash,subs="attributes+"]
 ----
-# Run complete installation
-make install ENV_FILE={env-file} CONN=<{conn-placeholder}>
+# Run complete installation (ENV_FILE defaults to .env)
+make install CONN=<{conn-placeholder}>
+
+# Or specify a custom env file
+make install CONN=<{conn-placeholder}> ENV_FILE=prod.env
 ----
 
 .. Option B: Step-by-Step Setup
@@ -118,10 +129,10 @@ Run each step individually:
 +
 [source,bash,subs="attributes+"]
 ----
-# Step 1: Generate snowflake.yml configuration
-make generate-yaml ENV_FILE={env-file}
+# Step 1: Generate snowflake.yml configuration (ENV_FILE defaults to .env)
+make generate-yaml
 
-# Step 2: Setup dbt Projects infrastructure
+# Step 2: Setup dbt Projects infrastructure (accountadmin + sysadmin objects)
 make setup-dbt-stack CONN=<{conn-placeholder}>
 
 # Step 3: Setup Slack connector infrastructure
@@ -137,6 +148,16 @@ make setup-procs-funcs CONN=<{conn-placeholder}>
 {streamlit-env-var}=true make deploy-streamlit CONN=<{conn-placeholder}>
 ----
 +
+[TIP]
+====
+*Quick start without Slack:* Use the `only-dbt` target to run steps 1+2+3+5+6 and load sample test data, skipping the Slack connector setup:
+
+[source,bash,subs="attributes+"]
+----
+make only-dbt CONN=<{conn-placeholder}>
+----
+====
++
 [NOTE]
 ====
 The Streamlit deployment step is optional and will only proceed if `{streamlit-env-var}` is set to `true`. If the environment variable is not set or set to any other value, the deployment will be skipped with a warning message.
@@ -192,15 +213,42 @@ Drop a test documents (PDFs, Word documents, etc.) in the bronze_zone.DOCUMENTS
 +
 Manually execute the Tasks available in the following order to build the baseline models and the Cortex AI services on top including the Cortex Agent:
 +
-* `incm_root_daily_incremental_refresh`
-* `incm_root_triggered_docs_processing`
-* `incm_root_deploy_cortex_services`
+* `incm_root_daily_incremental_refresh` — refreshes daily incremental models (incidents, comment history, etc.)
+* `incm_root_triggered_docs_processing` — processes newly uploaded documents (triggered by stream)
+* `incm_root_deploy_cortex_tools` — deploys Semantic View, Cortex Search service, and Cortex Agent
 +
 
 . Snowflake Intelligence
 +
 Once Cortex Agent has been created follow instructions link:https://docs.snowflake.com/en/user-guide/snowflake-cortex/snowflake-intelligence#add-agents[here] to add the Cortex Agent to Snowflake Intelligence.
 
+. Loading Sample Test Data (Optional)
++
+If you are not using the Slack connector or want to quickly populate the gold zone tables with sample data for testing, use:
++
+[source,bash,subs="attributes+"]
+----
+make load-test-data CONN=<{conn-placeholder}>
+----
++
+This uploads CSV seed files from `data/csv/` to the stage, creates gold zone tables, and loads the sample data. The tables created are: `incidents`, `active_incidents`, `closed_incidents`, `incident_comment_history`, `incident_attachments`, `document_full_extracts`, and `quaterly_review_metrics`.
++
+[NOTE]
+====
+This target uses `CREATE OR REPLACE TABLE` so it will overwrite existing gold zone tables. It is intended for initial setup and testing only.
+====
+
+. Redeploying the dbt Project (Optional)
++
+After pushing changes to the git repository (e.g., updated dbt models, macros, or agent specs), redeploy the dbt project in Snowflake:
++
+[source,bash,subs="attributes+"]
+----
+make redeploy-dbt CONN=<{conn-placeholder}>
+----
++
+This fetches the latest code from the git repository and adds a new version to the dbt project.
+
 . Streamlit Dashboard (Optional)
 +
 Optionally, you can deploy a Streamlit dashboard to visualize the incidents and their statuses as a more traditional method of reporting pre-calculated metrics and insights.

ascii-docs/cortex_agent.adoc

@@ -14,13 +14,19 @@ This page describes the approach taken by this project to deploy the Cortex Agen
 
 === Cortex Agent Deployment
 
-The Cortex Agent is deployed using the macro link:../src/incident_management/macros/create_cortex_agent.sql[`create_cortex_agent`] in Gold Zone. This macro is used to create the Cortex Agent with the given name, stage name, spec file, and agent profile.
+The Cortex Agent is deployed using the macro link:../src/incident_management/macros/create_cortex_agent.sql[`create_cortex_agent`] in Gold Zone. This macro accepts the following parameters: `agent_name`, `database`, `schema`, `stage_name`, `agent_spec_file`, and `next_version`.
 
-The actual definition of the Cortex Agent is stored in a YAML specification file that should conform to this link:https://docs.snowflake.com/en/sql-reference/sql/create-agent#required-parameters[Cortex Agent Specification], and is expected to be staged in gold_zone.agent_specs stage prior to the deployment of the Cortex Agent.
+The macro is *idempotent*: it checks whether the agent already exists in the database. If the agent does not exist, it creates it with `CREATE OR REPLACE AGENT` and registers it with Snowflake Intelligence. If the agent already exists, it updates the live version specification with `ALTER AGENT ... MODIFY LIVE VERSION` instead.
 
-A sample spec file is provided in the link:../src/cortex_agents/incm360_agent_1.yml[incm360_agent_1.yml] file, and is loaded during the Snowflake setup process.
+Each deployment is tagged with a version identifier and timestamp in the agent's `COMMENT` metadata, making it easy to track which spec version is deployed and when.
 
-This macro does not need to be run on a regular basis and can only be run when the composition changes in terms of tools, tool resources, or instructions, etc.
+The actual definition of the Cortex Agent is stored in a YAML specification file that should conform to this link:https://docs.snowflake.com/en/sql-reference/sql/create-agent#required-parameters[Cortex Agent Specification], and is expected to be staged in `gold_zone.agent_specs` stage prior to deployment.
+
+The current spec file is link:../src/cortex_agents/incm360_agent_v200.yml[incm360_agent_v200.yml], loaded during the Snowflake setup process by `03_procs_and_funcs.sql`.
+
+The agent spec is read from the stage at deployment time using a Python UDF (`READ_STAGE_FILE`) created in the `dbt_project_deployments` schema. The YAML content is passed verbatim into the `FROM SPECIFICATION` clause, preserving original indentation.
+
+This macro does not need to be run on a regular basis and can only be run when the composition changes in terms of tools, tool resources, or instructions, etc. It is invoked via the `incm_deploy_cortex_agent` task in the Cortex services deployment task graph.
 
 Having Cortex Agent created will allow you to use it in Snowflake Intelligence to answer questions about the incident management process. Post installation you will be required to add this explicitly to Snowflake Intelligence as described link:https://docs.snowflake.com/en/user-guide/snowflake-cortex/snowflake-intelligence#add-agents[here].