Commits: 2
Split the tagging and failing scenarios from the basic-usage suite
index 411d5d7..fb1caf7 100644
--- a/spec/basic-usage.md
+++ b/spec/basic-usage.md
@@ -190,22 +190,3 @@ Notice it's similar to the output of `tbb list`, but now contains unicode symbol
=## Running without a subcommand
=
=Running `tbb` without a subcommand will print the help message (to stderr) and exit with code 2.
-
-
-## A whole scenario failure
-
-Sometimes the failure is not in any particular step, but in a whole scenario, e.g. when an interpreter misbehaves. The status code and the summary should reflect it.
-
-
-## Multiple scenarios failure
-
-When several different scenarios fail, each one should be mentioned in the summary.
-
-
-## Tags are always in alphabetical order
-
-Consider moving it to a new Tags suite.
-
-## Tagging is idempotent.
-
-Tags are a set. Specifying the same tag more than once doesn't have any effect.index 274adcc..c0c4dec 100644
--- a/spec/failing-interpreters.md
+++ b/spec/failing-interpreters.md
@@ -4,7 +4,7 @@ interpreter: python -m spec.self-check
=
=# Failing interpreters
=
-This suite describes what should happen when the interpreter process misbehaves in various ways.
+Sometimes the failure is not in any particular step, but in a whole scenario, e.g. when an interpreter misbehaves. This suite describes what should happen when the interpreter process misbehaves in various ways.
=
=
=## Some won't start
@@ -41,3 +41,21 @@ If some interpreters' commands are invalid (e.g. refers to a non-existing progra
= * The standard error will contain `\[.+ ERROR +tbb\] Scenario failed: Suite 1 from the invalid document ❯ Hopeless scenario`
=
= * The exit code should be `1`
+
+
+## Multiple scenarios failure
+
+When several different scenarios fail, each one should be mentioned in the summary.
+
+
+## The interpreter won't indicate it's ready
+
+What if the process starts, but never sends any messages to output, specifically the `Ready` message? There should be a timeout period (with a default value of 10s, but configurable per scenario). After the timeout, the interpreter process should be terminated and scenario marked as failed. The output should clearly indicate what the problem was.
+
+This is currently **not implemented**.
+
+## The step is never resolved
+
+Similarly, if a single step is never reported as success of failure, the interpreter process should be terminated, and **the step** marked as failed.
+
+This is currently **not implemented**.new file mode 100644
index 0000000..efe375a
--- /dev/null
+++ b/spec/tagging.md
@@ -0,0 +1,39 @@
+---
+interpreter: "python -m spec.self-check"
+---
+
+# Tagging
+
+Suites and scenarios can be tagged. This is useful for [filtering](./filtering.md "Filtering spec").
+
+
+## Setting tags for a suite via a front-matter
+
+A front-matter of a spec document can have `tags` property with an array of tags. They will be applied to suites originating from this document.
+
+
+## Setting tags for a suite via `tbb` code blocks
+
+With a code block like this:
+
+ ``` yaml tbb
+ tags: [ "tag-1", "tag-2" ]
+ ```
+
+A code block must be placed before any scenario heading (h2).
+
+When multiple blocks are present, the tags should be merged.
+
+## Setting tags for a scenario via `tbb` code blocks
+
+Similar to a suite, scenario tags can be applied via (and only via) a `tbb` code block. Those blocks are placed after the given scenario heading. Other than that, same rules apply.
+
+
+## Tags are always printed in alphabetical order
+
+When printing a spec or a report, the tags should always be shown in alphabetical order.
+
+
+## Tagging is idempotent.
+
+Tags are a set. Specifying the same tag more than once doesn't have any effect.Update the readme, stub the source info spec
index 0db1bf3..8d5f4a0 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,7 @@ A BDD test runner inspired by Gauge, but better.
= * No magic
= * Flexibility
= * Cross-platform
+ * Batteries included, but replaceable
=
=
=## No magic
@@ -32,6 +33,11 @@ and even the original markdown fragment itself.
=Support for Linux, BSD, OS X and Web (WASM).
=
=
+## Batteries included, but replaceable
+
+The program comes with a versatile interpreter (not yet implemented) capable of web-automation via webdriver, an http client and command execution capabilities. It's also easy to implement your own interpreter. All it takes is reading JSON from `stdin` and writing JSON to `stdout`.
+
+
=## Vocabulary
=
=<!-- TODO: Reformat vocabulary as a definition list? -->new file mode 100644
index 0000000..19f98e2
--- /dev/null
+++ b/spec/source-information.md
@@ -0,0 +1,25 @@
+---
+interpreter: "python -m spec.self-check"
+---
+
+# Passing source information
+
+When executing a step, the interpreter will get it's source file path and lines range, like this:
+
+``` json
+{
+ "variant": "...",
+ "arguments": [],
+ "tables": [],
+ "source": {
+ "document_path": "./important-aspect.md",
+ "first_line": 23,
+ "last_line": 45
+ },
+ ...
+}
+```
+
+This is to fulfill the "batteries included, but replaceable" principle. With this information, an interpreter can extract any additional information from a step.
+
+