Merge branch 'mindplay-dk-patch-1'

Resources/doc/index.md

@@ -1,12 +1,25 @@
-Get starting
-============
-
-1. [Required dependencies](index.md#required-dependencies)
-2. [Installation](index.md#installation)
-3. [Usage](usage.md)
-4. [Configuration](config.md)
-5. [Event](events.md)
-6. [FAQs](faqs.md)
+Getting started
+===============
+
+1. [Introduction](index.md#introduction)
+2. [Required dependencies](index.md#required-dependencies)
+3. [Installation](index.md#installation)
+4. [Usage](usage.md)
+5. [Configuration](config.md)
+6. [Event](events.md)
+7. [FAQs](faqs.md)
+
+## Introduction
+
+Foxy is a Composer plug-in that aggregates npm-packages from Composer packages.
+
+This makes it possible (and automates the process of) installing and updating npm-packages that ship with your Composer packages, leveraging the native (`npm` or `yarn`) package manager to do the heavy lifting.
+
+For this approach to work well, you should think of an npm-package in a Composer package not just as an "artifact", but as an actual npm-package *embedded* in your Composer package.
+
+Importantly, you should name it and *version* it, independently of your Composer version number - like you would normally do with a stand-alone npm-package.
+
+Note that, for npm-packages with no version number, Foxy will default to the Composer version, as a fallback only: versioning your npm-package explicitly is much safer in terms of correctly versioning breaking/non-breaking changes to any client-side APIs exposed by the embedded npm-package.
 
 ## Required dependencies