docs(samples): publish 7 directive-syntax sample tutorials

_snippets/btp-trial-setup.md

@@ -0,0 +1,14 @@
+---
+params:
+  - name: region
+    required: true
+    default: us10
+---
+
+Follow these steps to create a BTP Trial account in region **{{param:region}}**:
+
+1. Navigate to [SAP BTP Trial](https://account.hanatrial.ondemand.com/).
+2. Select region `{{param:region}}` during signup.
+3. Complete the registration form and confirm your email.
+
+> **Note:** Free trial accounts expire after 365 days. Renew before expiry to keep your data.

tutorials/directive-authoring-aids/directive-authoring-aids.md

@@ -0,0 +1,142 @@
+---
+parser: v2
+auto_validation: false
+time: 10
+tags: [ tutorial>beginner, topic>developer-tools ]
+primary_tag: topic>developer-tools
+author_name: SAP Developer Advocates
+author_profile: https://github.com/sap-tutorials
+---
+
+# Use Authoring Aids to Annotate and Review Tutorials
+<!-- description --> Demonstrate the three authoring aids built into the tutorial platform: inline and block author notes (`%% … %%`), QA-only content blocks (`:::qa-only`), and the `deprecated-cli` freshness lint rule — tools that help authors and reviewers collaborate without affecting what production readers see.
+
+## You will learn
+- How to embed reviewer comments directly in tutorial source with author notes
+- How to include content that is visible only on the QA channel
+- How the CLI freshness linter catches outdated commands at build time
+
+## Prerequisites
+
+- You have write access to a repository under the `sap-tutorials` GitHub organization
+- You have the QA author-preview channel available at `/tutorials-qa/`
+- You have Node.js installed locally
+
+---
+
+### Step 1: Add Author Notes to Mark Content for Review
+
+Author notes let you leave comments for co-authors and reviewers directly in the
+tutorial markdown. They are stripped before the HTML reaches production readers.
+
+An inline note sits on the same line as prose, delimited by `%%`:
+
+```markdown
+Run the deployment command below %% @reviewer: confirm this works with SDK v4 — see issue #321 %% and wait for the output.
+```
+
+<!-- The inline author note above is intentional. On QA it renders as a styled
+     callout showing "@reviewer: confirm this works with SDK v4". On PROD the
+     entire %% … %% span is removed and readers see only the surrounding prose. -->
+
+A block note spans multiple lines. A bare `%%` opens it and a bare `%%` closes it:
+
+```markdown
+%%
+@author: The screenshot below is from the old tenant. Replace once the
+new BTP tenant is provisioned — tracked in https://github.com/sap-tutorials/…/issues/88.
+%%
+```
+
+<!-- The block note above shows a multi-line example. On QA it renders as a
+     block callout attributed to "author". On PROD it is replaced with a single
+     blank line so surrounding paragraphs remain separated. -->
+
+%% @reviewer: Does the step flow here feel natural for a new author? Consider splitting into sub-steps if needed. %%
+
+After you add a note, open the tutorial on the QA channel to verify it renders
+as a callout. When the content is finalized, remove the notes before promoting
+the tutorial to PROD.
+
+### Step 2: Add QA-only Blocks for Reviewer Context
+
+Sometimes you want to leave instructions for your reviewer that are not part of
+the published content at all. Use a `:::qa-only` directive for this.
+
+The block below is visible on the QA channel only. On PROD it is stripped
+entirely, including this sentence:
+
+:::qa-only[Reviewer checklist — remove or resolve before PROD promotion]
+Before approving this tutorial for PROD, verify:
+
+- The screenshots in Step 1 match the current BTP Cockpit UI
+- The time estimate (10 minutes) is realistic for a new developer
+- All code fences use the correct language tag (`bash`, `typescript`, etc.)
+- No author notes (`%% … %%`) remain in the source
+
+This block will not appear in the published tutorial. It is visible only on
+`/tutorials-qa/` when you are logged in with the `Tutorial.Author` scope.
+:::
+
+<!-- The :::qa-only block above demonstrates how to embed reviewer checklists.
+     The label "Reviewer checklist — remove or resolve before PROD promotion" is
+     shown as the callout header on QA. The body (the bullet list) is shown below
+     it. On PROD, the entire block including the label and body produces no HTML. -->
+
+After reviewing the tutorial on QA, the block can stay in the source until the
+review is complete. Remove it (or leave it if it is permanently useful for
+future reviewers) before the final PROD push.
+
+%%
+@author: We could keep this qa-only block permanently as a standard review checklist.
+Check with the team whether we want a shared template or per-tutorial checklists.
+%%
+
+### Step 3: Understand CLI Freshness Lint Findings
+
+The tutorial platform runs `lint-tutorial-markdown` during `npm run build:all`.
+One of its rules, `deprecated-cli`, scans every shell code fence for known
+deprecated CLI commands.
+
+The following example contains a deprecated `cf push` flag that the linter
+catches at build time:
+
+```bash
+cf push myapp --hostname myhost
+```
+
+<!-- The bash fence above intentionally uses the deprecated --hostname flag.
+     At build time the lint rule emits:
+
+     [deprecated-cli] directive-authoring-aids.md:N
+       The `--hostname` flag was removed in cf CLI v8. Use `routes:` in the
+       application manifest instead.
+       Replacement: Add `routes:\n  - route: <hostname>.<domain>` to manifest.yml
+       Docs: https://docs.cloudfoundry.org/devguide/deploy-apps/manifest-attributes.html#routes
+       Excerpt: cf push myapp --hostname myhost
+
+     In a real tutorial, update the command to use the manifest-based approach shown below. -->
+
+The corrected command uses an application manifest instead:
+
+```yaml
+# manifest.yml
+applications:
+  - name: myapp
+    routes:
+      - route: myhost.cfapps.eu10.hana.ondemand.com
+```
+
+```bash
+cf push myapp
+```
+
+%% @author: The deprecated example above is intentional — it demonstrates what the linter catches. Do NOT fix it before the sample is reviewed by the team. %%
+
+To run the linter locally against a single tutorial:
+
+```bash
+npx tsx scripts/lint-tutorial-markdown.ts directive-authoring-aids
+```
+
+Pass `--strict` if you want a non-zero exit code when findings are present (useful in CI pre-checks).

tutorials/directive-callouts/directive-callouts.md

@@ -0,0 +1,184 @@
+---
+parser: v2
+auto_validation: false
+time: 10
+tags: [ tutorial>beginner, topic>abap-development ]
+primary_tag: topic>abap-development
+author_name: Platform Team
+author_profile: https://github.com/sap-tutorials
+---
+
+# Tutorial Callout Enhancements
+<!-- description --> Demonstrate every callout the platform renders: the five standard alerts (NOTE, TIP, IMPORTANT, WARNING, CAUTION), collapsible DETAILS / TROUBLESHOOT / HINT / SOLUTION / RESULT callouts, inline spoilers, and the `:::type[Title]` directive equivalents.
+
+## You will learn
+- Which alert designators the platform recognizes and when to reach for each
+- How to use collapsible DETAILS, TROUBLESHOOT, HINT, SOLUTION, and RESULT callouts
+- How to blur an answer inline with `:spoiler[...]`
+- How the `:::type[Title]` directive form maps to the blockquote form
+
+## Prerequisites
+- Familiarity with the basic tutorial markdown structure (see [v2-example-tutorial](../v2-example-tutorial/v2-example-tutorial.md))
+
+---
+
+### Step 1: Standard alert callouts
+
+The five standard alert types (NOTE, TIP, IMPORTANT, WARNING, CAUTION) are non-collapsible
+and render with an icon. Use them for emphasis, not decoration.
+
+> [!NOTE]
+> This is a note. Use it for supplementary information that doesn't interrupt the flow.
+
+> [!TIP]
+> This is a tip. Use it for helpful shortcuts or best practices.
+
+> [!WARNING]
+> This is a warning. Use it when the reader could lose work or cause unexpected behavior.
+
+> [!CAUTION]
+> This is a caution. Use it for severe or irreversible consequences.
+
+> [!IMPORTANT]
+> This is important. Use it for key information the reader must not miss.
+
+Any alert type accepts an optional title after the designator:
+
+> [!NOTE] Custom heading
+> This note has a custom heading above its body text.
+
+### Step 2: DETAILS callouts
+
+DETAILS is a collapsible section. A title is **required**. By default the section starts
+closed; append `+` to start it open.
+
+> [!DETAILS] Closed by default — click to expand
+> This content is hidden until the reader clicks the heading.
+>
+> It can contain multiple paragraphs, lists, and code blocks.
+>
+> ```yaml
+> key: value
+> ```
+
+> [!DETAILS+] Open by default — click to collapse
+> This content is visible immediately. Use `+` when the reader is likely to need the
+> content on a first pass but it would clutter the step if always-visible.
+
+### Step 3: TROUBLESHOOT callouts
+
+TROUBLESHOOT callouts are collapsible and contribute to the auto-generated troubleshooting
+index at the bottom of the tutorial. A title is optional but recommended.
+
+> [!TROUBLESHOOT] `cds watch` exits immediately with "No service definition found"
+> Ensure at least one `.cds` file in `srv/` contains a `service` definition. Check that
+> `package.json` lists the correct `cds.roots` paths.
+>
+> ```bash
+> ls srv/*.cds
+> ```
+>
+> If the folder is empty, you may have cloned the wrong branch.
+
+> [!TROUBLESHOOT] Port 4004 is already in use
+> Another `cds watch` process is running. Kill it first:
+>
+> ```bash
+> npx kill-port 4004
+> ```
+
+### Step 4: RESULT callouts
+
+RESULT marks the expected outcome after completing an action. It has a default title of
+"You should see" and a checkmark icon. Place it immediately after the action step.
+
+Run the build:
+
+```bash
+npm run build
+```
+
+> [!RESULT]
+> The terminal prints `Build succeeded` and exits with code 0. The `dist/` folder now
+> contains `index.html`.
+
+You can also provide a custom title:
+
+> [!RESULT] Terminal output
+> ```
+> ✓ 3 tests passed
+> ```
+
+> **Note:** Automatic verification links (assert-link) for RESULT callouts are deferred
+> to a follow-up feature.
+
+### Step 5: HINT and SOLUTION callouts
+
+Multiple HINT callouts in the same step unlock one at a time — the reader must open the
+first before the second becomes visible. Place SOLUTION at the end of the exercise.
+
+**Exercise:** What CAP annotation marks a service endpoint as read-only?
+
+> [!HINT]
+> Look at the service definition in `srv/cat-service.cds`.
+
+> [!HINT]
+> The annotation starts with `@readonly`.
+
+> [!HINT]
+> It is placed before the entity projection inside the `service` block.
+
+> [!SOLUTION]
+> Add `@readonly` before the entity projection:
+>
+> ```cds
+> service CatalogService {
+>   @readonly entity Books as SELECT from my.Books;
+> }
+> ```
+
+### Step 6: Inline spoilers and directive syntax
+
+Use `:spoiler[text]` to blur an answer inline — useful for quiz-style prompts:
+
+Which SAP framework is used to build cloud-native business applications? :spoiler[CAP (Cloud Application Programming Model)]
+
+In plain-text contexts (MCP tool, email) the spoiler renders as `||CAP (Cloud Application Programming Model)||`.
+
+The `:::details[Title]` directive syntax is equivalent to `> [!DETAILS] Title` and is
+useful when the body contains content that is awkward inside a `>` blockquote:
+
+:::details[Full configuration file]
+```yaml
+cds:
+  requires:
+    db:
+      kind: hana
+  features:
+    ieee754compatible: true
+```
+:::
+
+### Step 7: Directive equivalents for HINT and SOLUTION
+
+All collapsible callout types have a `:::type[Title]` directive equivalent. This form is
+interchangeable with the blockquote form.
+
+:::hint[Need a hint?]
+Check the CAP documentation for `cds.ql` query examples.
+:::
+
+:::solution[Full solution]
+```js
+const books = await SELECT.from('my.Books').where({ author_ID: authorId })
+```
+:::
+
+:::troubleshoot[Module not found: @sap/cds]
+Run `npm install` to restore node_modules, then verify `@sap/cds` is listed in
+`dependencies` (not `devDependencies`) in `package.json`.
+:::
+
+:::result
+The application starts without errors and the terminal shows `Server is listening on port 4004`.
+:::